Markdown versus ReStructuredText

Question

What are people's thoughts on the pros and cons of Markdown versus ReStructuredText. Both seem like very usable and well-developed markup languages -- when might one want to use one over the other?

Answer 1

Not that popularity is everything, but Google lists about 337,000 results for ReStructuredText vs 3,040,000 for markdown.

Even assuming lost of other users for the word markdown, it would appear to be a much more popular option, and hence a better default choice unless ReStructuredText offers something compelling I'm not aware of.

Answer 2

There's plenty of markup languages around - Textile, Wiki Markup, etc - and to be honest it seems to be personal preference or previous use rather than feature set that influences usage. There should be no reason to not support a few markup language if there's robust libraries for your language. I went round in circles over this on a project and eventually decided to support textile and markdown and let the user decide.

Answer 3

I feel markdown succeeds where other markup languages fail because the author didn't try to create a new language, but rather codify what people were doing already (specifically in emails).

From Markdown's home page:

While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

To examplify why I think RST fails, I think both double colons and double back-quotes are obscure and hard to get right.

Answer 4

Markdown seems useful if you're mainly interested in generating HTML. ReStructuredText (and the related DocUtils suite) is good if you want to generate other structured output formats (eg LaTeX). Sure, you can generate your LaTeX from HTML, but generating it directly from the source will likely give you cleaner LaTeX and keep all your semantics intact. Source -> HTML -> Target may lose some of your meaning.

Also, ReStructuredText is extensible (you can add your own "directives"). So you can add semantic constructs and choose how you want to render them in each output format.

In short, Markdown looks great for web pages; ReStructuredText is great for documentation, books, and other areas where you want other (and multiple) formats.

Answer 5

ReST is in some sense a superset of Markdown, and this is the single most important point to understand. While Markdown is aimed at simple markup like the one here on SO, ReST is also suitable for building whole documents, with tables of contents, indices, footnotes and so on.

So if you need something simple, Markdown is probably the best option. But if you're looking at more advanced needs like structuring whole documents and an extensible system that helps you with kinky stuff, ReST is the preferred choice.

Answer 6

Building on what Jason McLaren said, the basic point is that Markdown and Restructured Text are typically used for two different purposes. Markdown tends to be used more for things like blogging, discussion postings, and other applications like that.

On the other hand, ReStructured Text (IIRC) was made specifically for being easy to insert into source code. For example, I did work on a python project that would embed the documentation into its source code (encoded into Restructured Text). The documentation on the main webpage was basically that documentation code pulled from the files in trunk.

Answer 7

I've long been a fan of reStructuredText. Recently Python's official documentation was converted from LaTeX to rST and the results are impressive. Sphinx, the tool they use to manage the publishing, is coming along nicely.

That said, I have to admit that editing rST in anything other than emacs seems strange and unnatural. Many of its formatting conventions seem designed to mesh well with how emacs behaves WRT wrapping text and the like. So, while I like it because I'm an old emacs hacker, my colleagues -- not so much.

Markdown, on the other hand, seems more text-editor agnostic because it is a much simpler format. If I could convince my colleagues to go plain-text for documentation, this is the variant I'd advocate. (As it is, I've convinced them to use OpenOffice's HTML support which is at least reasonably diff/merge-friendly.)

Hmm, on second thought it OO's HTML isn't all I'd hoped for in that regard. It's pretty ugly in that regard. I find I've been sucessively converting any documents I need to maintain to markdown because that helps to keep me sane.

If you anticipate needing to publish your documentation in dead-tree format (LaTeX->PDF) consider rST. If HTML and markdown's more limited feature set is good enough go with markdown.

Answer 8

You can find WYSIWYG javascript editors for Markdown (stackoverflow uses one). I've yet to find one for ReST.

You can use ReST in python comments.

Answer 9

I don't know if this list is accurate, but see the difference on tables. It was really important when I had to choose.

Answer 10

Having used both I can say that ReStructuredText is much more mature and capable, and has fewer stupid limitations. For example, Markdown won't let me put a code snippet inside a numbered list without dropping into HTML. I wrote a whole book in ReST. That said, I'm using markdown right now on a wordpress blog (cpp-next.com) because nobody's written a PHP implementation of ReST, so momentum, popularity, and ease of implementation do count.

Answer 11

Late to the party, I know. My choice came down to not wanting to use one syntax for blogging and another for documentation, so I chose reSt. For Wordpress blogging the big obstacle was getting rid of the excess stylesheet and non-body HTML markup that comes with docutils.