Lightweight Markup: AsciiDoc, reStructuredText, and Markdown Compared

The earliest lightweight markup language was a typewriter.

A lightweight markup language is a form of markup — text whose formatting appears as inline annotations — designed to be lightweight. While some markup languages such as HTML, LaTeX, XML, and others can be difficult or unpleasant to read, lightweight markup languages are designed to be easy to read. Because lightweight markup is plain text, it’s portable, fairly future-proof, editable with any text editor, and easy to manage with source control tools. Though there are many specialized lightweight markup languages, three have become very popular for general use: AsciiDoc, reStructuredText, and Markdown.

Each has its advantages, but there is a lot of overlap as well: they all have their own ways of handling things like tables, footnotes, admonitions, links, and snippets, for example. Choosing one of these three markup languages is not a one-way street, because tools like Pandoc can handily convert among them.

There are disadvantages to using a lightweight markup language. Preserving certain types of formatting can be challenging when converting between document types, and not all markup languages are suited to managing long documents. If you are creating a printed technical manual or a complex academic paper, other tools might make the job easier. But for many purposes, a lightweight markup language…