Markup is not just HTML

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:

Markdown

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.

Use the 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.

AsciiDoc

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.

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:

Learn more at AsciiDoc's website.

reStructuredText

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:

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.