Flaviu's Blog - Read'n'Code

reStructuredText vs. Markdown

Markdown wins. (For generating html anyway)

Why? You decide for yourself:

Markdown is a perl file with a README on how to use it to convert text to html.

Installing reST means manually installing docutils, with these instructions because of course installing it with pip doesn’t give you the tools you need in the next step.

Then, in the tar ball there is a /tools directory in which all of the parsers are. Of which I only need rst2html.py, which I have to now put on the path.

In reST, the underline/overline for a title must be at least as long as the title text. Why? Markdown doesn’t care. It’s only semantic anyway.

Underscores, double colons and quotes are not easy to get right. Markdown feels more natural with parans.

So, markdown generates HTML fast and easily. reST has a greater depth with LaTeX and Sphinx, which is the best documentation generation tool ever.

This discussion was also nicely covered here.


Fork Flaviu on GitHub