Compare and contrast the lightweight markup languages (Textile, Markdown, and reStructuredText)

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
• 5 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...
• ... 47 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 <[email protected]> (with angle brackets)
• Syntax reference

reStructuredText (A.K.A. ReST)

• Popular in the Python community
• 3 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

Answer 2

You might also consider asciidoc

• relatively readable markup
• straightforward command-line use
• some might perceive it as relatively 'picky' (vs. flexible) with respect to syntax
• docbook and (x)html output

Answer 3

for documentation? how about doxygen?
I've use it for some of c/c++ project that I need to documentize. Even you can 'abuse' it just like doxygen author uses for doxygen documentation

Answer 4

txt2tags

Answer 5

I am attempting to cover all the various lightweight markup languages here:

http://www.subspacefield.org/~travis/static_blog_generators.html

As you can see, it started with "how can I make a secure blog" - i.e. one that generates static HTML, and I found myself ensnared in markup languages, templating systems, etc.

Answer 6

Update

I refocused only on LWMLs with python implementations, and theyre here:

http://www.subspacefield.org/~travis/python_lightweight_markup_languages.html

So far I've tried markdown and ReST, and I like the latter better for anything but HTML snippets embedded in other pages. Tables, cross refs, indirect links, etc...

Answer 7

The Wikipedia page on lightweight markup languages has a good comparison between the various options, as well as showing syntax for common uses (headings, bold, italics, etc.)