Question

Please identify the most popular lightweight markup languages and compare their strengths and weaknesses. These languages should be general-purpose markup for technical prose, such as for documentation (for example, Haml doesn’t count).

See also: Markdown versus ReStructuredText

Answer 1

I know of three main languages used commonly in the greater programming and tech community: Textile, Markdown, and reStructuredText. All three can be learned in a couple of hours or ‘winged’ with the cheat sheet nearby.

Textile

• Used by Redmine and the Ruby community
• 113 questions currently tagged on Stack Overflow
• The most similar to HTML, but least readable source
• Easiest nested lists of all three languages
• Not understandable to non-programmers or the HTML-ignorant
• Ideal for complex short documents (with links, nested lists, code, custom HTML); for example: short documentation, how-tos, blog or CMS content
• Syntax reference

Markdown

• Doesn’t seem to have a home language ‘community’ but…
• 1274 questions tagged on Stack Overflow*
• Emphasizes source code readability, similar to email traditions
• Straightforward HTML embedding (you just type the tags out)
• No way to make tables besides embedding HTML
• You know it already if you know Stack Overflow
• Easy to learn if you already know reStructuredText
• Automatic email address obfuscation for the format <[e-mail]> (with angle brackets)
• Syntax reference

reStructuredText (A.K.A. ReST)

• Popular in the Python community
• 285 questions tagged on Stack Overflow
• A bit persnickety about whitespace and alignment if you ask me
• Lists (especially nested lists) and paragraphs always seem to get in fights
• Readable by non-programmers
• Only format which can build a table of contents (via an extension in the Python reference implementation)
• Directly converts to other formats like PDF and XML
• Ideal for large documents with lots of prose (e.g. an alternative to docbook for a user manual)
• Syntax reference