Pandoc Markdown and ReST Compared

John Gabriele

2018-07

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:

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,

for i in range(10):
    print "hi", i

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).

Links

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:

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.