Markup is not just HTML
Technical writers need to be familiar with a variety of markup tools. Here's a rundown of three popular markup systems.
In 2023, you might associate "markup" with "HTML." But the technical communication field relies on more than just HTML to provide document markup. Here are a few other examples of document markup you might not know about:
If you find markup tags distracting when writing technical documents, try Markdown. We've covered Markdown before, but it's worth exploring further - especially because Markdown appears everywhere, including on GitHub.
Markdown tries to adopt text formatting conventions that have become more or less standard since the days of plain text files. For example, to indicate a title, underline it with equals signs (a "double underline"). Underline section headings with dashes (a "single underline").
This is a sample Markdown document ================================== Markdown tries to emulate the same conventions often found in plain text Readme files. For example, to make a title, underline it with "equals" signs. For a section title, use dashes. Sample formatting ----------------- Markdown lets you write documentation without formatting "tags" getting in the way. For example, you can use **bold** or *italics* or _italics_ or `code` to format your text. Add numbered lists by typing numbers: 1. The first item 2. The next item 3. The last item And bullet lists by typing a bullet: * The first item * The next item * The last item ## More Info ## Refer to the [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/) for more information about using Markdown.
Markdown.pl script to convert your Markdown document into HTML:
$ Markdown_1.0.1/Markdown.pl sample.md > sample.html
For more information, visit Daring Fireball's Markdown page.
The AsciiDoc markup system provides document markup for writing about technical topics. Similar to Markdown, AsciiDoc aims for flexible features and semantic elements.
For example, to format text as bold, surround the text with asterisks. To put text in italics, use underlines.
= About AsciiDoc This is an example of an *AsciiDoc* markup system. AsciiDoc aims to provide simple document markup that doesn't get in the way of your technical writing. AsciiDoc documents should look like regular text files, and the AsciiDoc system converts the minimal markup as it generates a new version. AsciiDoc supports formatting like *bold* and _italics_ and `code` formatting. If you really need to emphasize a point, you can mix and match like *_bold and italics_*. == More Info Refer to the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Quick Reference Guide] for more things you can do with AsciiDoc.
asciidoc command line lets you convert the source file into a variety of output types, including DocBook, HTML, or LaTeX. To convert the sample file into HTML, use this:
$ asciidoc -b html5 sample
The output will be saved automatically into a file called
Learn more at AsciiDoc's website.
The reStructuredText system is part of Python, and provides a document markup similar to Markdown and AsciiDoc. reStructured uses plain text formatting like asterisks for italics and double asterisks for bold.
But reStructuredText's strength is in how easily it manages lists that might include sub-items of mixed types, such as a numbered list with a bulleted sub-list for one item and an enumerated sub-list for another item.
Using reStructuredText ====================== Writing a reStructuredText (RST) file is much like writing a plain text file. With RST, you can focus on the content of your document without worrying about the formatting tags to make it look pretty. RST will do all that for you. You can format text in *italics* or **bold** or ``code``. Note that RST doesn't interpret other code between the back ticks, so ``*italics*`` is just displayed as inline code. (Refer to the source to see how this was entered.) Lists ----- Add numbered lists by typing numbers: 1. The first step 2. The second step 3. The third step Or bullet lists with a bullet: * The first item * The next item * The last item Or mix and match like this: 1. A new numbered list * A bullet list inside the first step * The next item * The last item 2. The second step a. You can have letters in lists too b. The next sub-step c. The last sub-step 3. The last step - You can use all kinds of bullet characters - This one uses hyphens Code ---- To insert a code block, use as double colon to start:: #!/bin/bash for n in $(seq 1 10) ; echo $n.txt ; done When text returns to the initial indent level, the code block stops.
If you have the Python3 DocUtils package installed on your system, run the
rst2html command to convert your reStructuredText file into HTML:
$ rst2html sample.rst > sample.html
The output will be saved to
sample.html, which you can view in a web browser: