On: Pandoc Markdown and ReST Compared (2013)

[egh]

The really nice thing about ReST is that it has provided generic syntax for extensions, one for inline text: :foo:`hello world` and for blocks:

.. extension:: hello world

In markdown, on the other hand, you have multiple, incompatible versions which have entirely different syntax because there is no generic extension mechanism.

ReST feels more well thought-out, generally.

That said, I've pretty much given up advocating it, because markdown seems to have won and has so much more tool support.

[BruceM → egh]

I like ReST as well. With Sphinx, it is great for producing documentation. A project that I work with has converted hundreds of pages of books of technical documentation over to Sphinx and a custom Sphinx extension.

[fprintf → BruceM]

I like ReST as well.

It's more powerful and looks much cleaner

// e.g. how do you write footnotes in markdown? And how do you do this in markdown?

  +------------+------------+-----------+
  | Header 1   | Header 2   | Header 3  |
  +============+============+===========+
  | body row 1 | column 2   | column 3  |
  +------------+------------+-----------+
  | body row 2 | Cells may span columns.|
  +------------+------------+-----------+
  | body row 3 | Cells may  | - Cells   |
  +------------+ span rows. | - contain |
  | body row 4 |            | - blocks. |
  +------------+------------+-----------+

[mercurial → fprintf]

Since basic Markdown is so basic, multiple incompatible flavours of Markdown have cropped up, including Pandoc-Markdown, which can do footnotes.

[biscarch → fprintf]

in pandoc-markdown a footnote[^1] would be written like this.

[^1]: My footnote here

Here's a link to pandoc's markdown flavor, which includes tables: http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markd...

[masklinn → egh]

> ReST feels more well thought-out, generally.

It's certainly set up for extensibility, although some areas are a pain (e.g. blank lines may be ignored entirely, change vertical spacing or change semantics, that can be annoying).

The toolchain is also fairly complex and very badly documented (Sphinx itself is better documented than docutils, but either way you end up wading through piles of code to understand what happens, why, and what's available in the applicative context of your extension)