Pandoc Markdown and ReST Compared John Gabriele

Markdown is a very popular plain text markup format, but the Python community uses an alternative called reST.

Markdown usage is pretty ubiquitous; it’s used by many blogs, and sites like Reddit, GitLab, GitHub, StackOverflow, etc. The Python project uses reST, and has the Sphinx doc processing tool generate their html docs, as do many other Python-based projects.

This somewhat opinionated document (I prefer Markdown to reST) compares some syntax differences between Markdown (in particular, Pandoc’s Markdown) and reST syntax. Please note that, anywhere I say “Markdown” below, if there’s any ambiguity, I specifically mean the “Pandoc Markdown” flavor. Gruber’s original Markdown lacks a number of the modern niceties which Pandoc-Markdown tastefully provides.

To try out examples yourself:

Install Pandoc on a Debian-based distro like so: sudo apt install pandoc . Prepare a ~/temp/foo.txt document and process it like so: pandoc -s -o foo.html foo.txt

Install docutils on a Debian-based distro like so: sudo apt-get install python-docutils . Prepare a ~/temp/foo.rst document and process it like so: rst2html foo.rst foo.html

Headings

Pandoc-Markdown reST An H1 heading ============= foo bar baz An H2 heading ------------- foo bar baz ### An H3 heading ### foo bar baz #### An H4 heading #### foo bar baz An H1 Heading ============= foo bar baz An H2 Heading ------------- foo bar baz An H3 heading ~~~~~~~~~~~~~ foo bar baz An H4 heading ````````````` foo bar baz

The characters chosen to underline the reST H3 and H4 headings are mostly arbitrary; different people use different ones. When working on large documents, personally I prefer Markdown style — it’s easier to visually discern the main sections and subsections without getting distracted by lower subsections.

Markdown allows you to use “ # H1 # ” and “ ## H2 ## ” (and even just “ # H1 ” & “ ## H2 ”), but I find those somewhat less readable than what’s shown above.

Title Block

You can start your document in such a way as to include metadata such as title, author, and date:

Pandoc-Markdown reST % Title % Author Name % 2012-04 The rest of the doc ... ======= Title ======= ------------------- Optional Subtitle ------------------- :Author: Author Name :Date: 2012-04 The rest of the doc ...

Italic, Bold, Code

Pandoc-Markdown reST *Italic*, **bold**, `code`. block of code goes like this Or, as an alternative, delimited blocks are supported too: ~~~ block of code goes like this ~~~ A syntax-highlighted code block: ~~~python for i in range(10): print "hi", i ~~~ *Italic*, **bold**, ``code``. :: block of code goes like this A syntax-highlighted code block: .. code:: python for i in range(10): print "hi", i

ReST requires two backticks around inline code, which gets tiresome to type. It also requires a double colon (either ending the preceding paragraph, or else as shown above) for code blocks.

With Pandoc-markdown delimited blocks, you can use the triple-tilde or the triple-backtick. Since delimited blocks don’t need to be indented, they can save time when copying/pasting code from source files to documents.

Pandoc can do syntax highlighting of code blocks,

and my understanding is that docutils can do that as well, though I wasn’t able to get it working with docutils (version 0.8.1).

Pandoc-Markdown reST Please find [a link to the site](http://example.com/). Also useful is [this site], as you may have heard. [this site]: http://example2.com Here comes an image: ![alt text](path/to/image.png) Finally, don't miss <http://example3.com>. Please find `a link to the site <http://example.com>`_. Also useful is `this site`__, as you may have heard. __ http://example2.com (Alternate) Also useful is `this site`_, as you may have heard. .. _this site: http://example2-2.com Here comes an image: .. image:: path/to/image.png Finally, don't miss http://example3.com.

Personally, I regularly forget the reST link syntax.

Also, reST automatically converts things that look like urls to links (see the last line above), but it’s smart about not including trailing punctuation in the linked-to url (at least, for the cases I tried). That said, bare urls with trailing punctuation look a bit weird to me. Regardless, I prefer the Markdown style of always putting angle brackets around urls so that (A) they stand out better, and (B) there’s no ambiguity about what’s included in the url.

Lists

Pandoc-Markdown reST Unordered list: * item 1 * item 2 * item 3 A longer one: * this is a long, multi-line paragraph. It seems to go on and on. * this is a long, multi-line paragraph. It seems to go on and on. Here's a code block within the list item. Here's a second paragraph, still part of the 2nd item. * this is a long, multi-line paragraph. It seems to go on and on. Numbered: 1. won 2. too 3. tree Definition list: foo : a foo-like object bar : barium baz : my third and final def list item Done. Unordered list: * item 1 * item 2 * item 3 A longer one: * this is a long, multi-line paragraph. It seems to go on and on. * this is a long, multi-line paragraph. It seems to go on and on. :: Here's a code block within the list item. Here's a second paragraph, still part of the 2nd item. * this is a long, multi-line paragraph. It seems to go on and on. Numbered: 1. won 2. too 3. tree Definition list: foo a foo-like object bar barium baz my third and final def list item Done.

I think a major win for Pandoc-Markdown here is that, when dealing with any kind of list, list content (not the marker, but the text itself) can always start in at a multiple of 4 spaces/cols. Code is the same, but with no list marker. It’s simple and consistent, is easy to remember, looks good, and makes formatting deeply nested lists easy.

Blockquote

Pandoc-Markdown reST Here's a blockquote: > He said *this*. > I said *that*. Done. Here's a blockquote: He said *this*. I said *that*. Done.

With reST, the blockquote content looks to me like it might be a code block — I have to check if there’s a preceeding double-colon to be sure.

Tables

Pandoc-Markdown reST A table: Size Color Fragrance ---- ------ ---------------- 9 Red Excelsior 10 Blue Icey Cool 8 Green Breezy Meadow A multi-line table: ------------------------------------------- Orientation Reasoning ----------- ------------------------------ leftward Because it works well under extreme depths and pressures. spinward There's no reason to use spinward. It will only cause apoplexia. ------------------------------------------- Done. A table: ==== ===== ================= Size Color Fragrance ---- ----- ----------------- 9 Red Excelsior 10 Blue Icey Cool 8 Green Breezy Meadow ==== ===== ================= A multi-line table: =========== ============================== Orientation Reasoning ----------- ------------------------------ leftward Because it works well under extreme depths and pressures. spinward There's no reason to use spinward. It will only cause apoplexia. =========== ============================== Done.

Also, both markup formats support a “grid table” syntax as well.

Misc

Pandoc-Markdown reST Here's a horizontal rule: *** One minor footnote [^1] to be aware of. [^1]: footnote text goes here. You can simply <span class="yo">add html</span>, if necessary. You can also escape to LaTeX-formatted math: $a^2 = b^2 + c^2$. <!-- This is a long comment, spanning multiple lines. --> Here's a horizontal rule: ---- One minor footnote [1]_ to be aware of. .. [1]: footnote text goes here. To insert raw html, there's a ".. raw:: html" directive. You can use LaTeX-formatted math like so: :math:`a^2 = b^2 + c^2`. .. This is a long comment, spanning multiple lines.

It’s nice that reST has its own comment syntax, though I can’t say that it stands out very much from the rest of the document’s content.

reST supports autonumbering of footnotes, if you’d prefer to just write them with a number sign (like autonumbered enumerated lists).

For details on reST’s raw html directive, see the reST docs.

Field Lists

Pandoc-Markdown reST Pandoc Markdown doesn't have these. You might try for a similar effect like so: | **Name**: Fluxor | **Planet of origin**: Betatron 5 | **Special Skills**: Invisibility, Scent matching or maybe put them into a table, or a definition list. :Name: Fluxor :Planet of origin: Betatron 5 :Special Skills: Invisibility Scent matching

Conclusion

The two formats have other minor differences, including:

with Pandoc-markdown you can force a newline by ending a line with a backslash (note that both reST and Pandoc-Markdown support line blocks).

reST has “option lists” for listing options and args you might pass to a command-line program.

And of course there’s other sundry differences between them that you can read about in their respective documentation pages. In this article, I’m trying to sum up the major differences that you’ll notice when using them on a regular basis.

For multi-chapter documents, ReST has Sphinx. For processing multi-chapter possibly-nested Pandoc-Markdown docs, I cobbled together my own tool called Rippledoc.

My 2¢: Pandoc-Markdown is easier on the eyes, easier to remember, and even easier to type.