cat-computer 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](
for more information about using Markdown.

Use the script to convert your Markdown document into HTML:

$ Markdown_1.0.1/ > sample.html

Markdown sample

Markdown sample

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`

If you really need to emphasize a point, you can mix and match like
*_bold and italics_*.

== More Info

Refer to the[Quick
Reference Guide] for more things you can do with AsciiDoc.

The 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 sample.html:

AsciiDoc output

AsciiDoc output

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.)


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


To insert a code block, use as double colon to start::

  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:

reStructuredText output

reStructuredText output

You can also convert reStructured text files into LaTeX, man pages, ODT, and other types. For more information, visit A ReStructuredText Primer and the Docutils Readme.