Compare and contrast the lightweight markup languages

documentation markdown markup restructuredtext textile
JasonSmith picture JasonSmith · Mar 18, 2009 · Viewed 23.2k times · Source

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

JasonSmith picture JasonSmith · Mar 18, 2009

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 <[email protected]> (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

Related questions

How do I link between markdown documents in doxygen?

I have a project with a set of markdown pages that are interlinked with links such as [Go to this page](subdir/MyOtherPage.md) The pages all get picked up by doxygen and appear in the output, but the links …

Read More
How do I put blocks of PHP code into a PHPDoc DocBlock

I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code. However, I can't seem to figure …

Read More
What tools does your team use for writing user manuals?

Basic requests are: human readable / text format (for easy version control) online (for collaboration) easy formatting (markdown ok, html is too much) strict formatting (so authors don't invent new types of titles, bullets etc.) exportable to PDF, HTML easy backup …

Read More