comment 0

Markdown and ReST Compared

rstMarkdown and reStructuredText (ReST) are two heavily used markup languages on the WWW. While I would have expected at first that the markup language from Wikipedia to spread due to the high popularity of the web site, it is actually two other ones which became successful.

Markdown is heavily used in the blog world, while ReST comes from the Python world.  However, Markdown suffers from fragmentation and incompatibility in implementations, while ReST as a good specification and hooks for extensions.

I personnaly highly prefer RST. The following page will compare both markup syntaxe with a highly subjective point of view in flavor of ReST.


Here are the Markdown headings:

And the ResT:

My comments: I personally prefers the ReST syntax: it’s clearer, more linked to what I would naturally do.

You need to know that actually there is no stricto senso a proper syntax, like if you have to place “=” for H1, “-” for H2,… What you need to know is to place a line of a some special character (= - ` : ' " ~ ^ _ * + # < >) on the bottom of your title (or if you want on both top and bottom). This will be how all H1 in your current document will be recognized. If you choose another underline character, this will become the syntax for the H2 heading, and so on.

It’s a bit weird at first, but once you have properly understood how it work it become something very natural.

Title and subtitle

Markdown has a special syntax:

You don’t have subtitle support.

While ReST is more elegant:

My comment: I still prefer ReST, since it is clearly the same than section. A title is just a section with only children and no sibbling (no same level heading).

Italic and Bold

Markdown and ReST propose the same syntax:

Code block

This is the major drawback of ReST, or at least what I’ve read some forum. But I think there wrong, I thing ReST has a pretty well shaped syntax.

Let’s look at how Markdown declares inline code and code block

And now for ReST:

My comments: I largy prefer the ReST syntax for inline code, the double backticks helps identifying where the code is. It is however quite difficult to enter it on a french keyboard. Of course, both markup language has tools to generate syntax highlighted source code (pandoc for ReST and Markdown, and the wonderful Sphinx for ReST).

Link and URL

The Markdown syntax is the most natural but limited one:

The ReST syntax a bit tricky but much more powerful:

ReST automatically convert plain URL to hyperlinks without punctuation. Also, this syntax is perfectly suited to refer other sections of the document.

My comments: even though I find the Markdown syntax a bit more “natural”, meaning it’s like you can find on other markup language, like  on wikis (Wikimedia,…), I find the ReST version much more advanced. You’ll need to have a good editor however easing your work.

Inserting images



My comment:  I really like the ability in ReST to specify more information about the picture to describe, it’s size, alignment,…


Markdown has a very strict approach to lists:

While ReST:

My comments: You have to take care of leaving an empty line in ReST after block. I have to admit that the tool I use (Sphinx) doesn’t generate very human readable error when this line is not empty (it speaks about unaligned paragraph at the end of the file…). However, I clearly find the ReST version much clearer and natural.


Both use the same syntax:


My comment: My preference goes to Rest which is still a bit clearer in its syntax. But you have to take care of dividing will your lines of separators.


Markdown comments looks like HTML:

While rest is more coherent with the rest of its syntax:

My comments: Even if was disapointed by both, not having reused scripts comments (“#”) or practical syntax, I still prefer the ReST solution: simpler, easier, cuter.


This conclusion is highly personal: of couse I still prefer ReST, that’s why I’ve wrote this document. For me, ReST is mainly easier to use than Markdown, except for the block quote and table where you might need the read some documentation. But every markup language as this flaw. You need to learn the language and use the one you are most confortable with.