« Back to Blog

Behind the Scenes - Markdown vs. reStructuredText

By Jason Kölker
Jan 20, 2017

Markup languages are a great way to write documents that will be read in a variety of situations. Two of the most popular of the lightweight variety are Markdown and reStructuredText. Both are excellent choices compared to maintaining multiple formats of the same document, however, when given the opportunity, reStructuredText may be a better choice.

History

Back in the day, when kids stayed off my lawn, terminals were text only, sometimes without the ability to display bolded or italicized text. Various markups were employed to convey these styles as an alternative to going without emphasis.

Formally this evolved into the SGML standard, informally simple character shortcuts continued to be used in plain text documents. SGML evolved to gain the XML profile and HTML as once of its descendants.

The informal shortcuts started to be formalized for use in newsletters. This allowed readers to view the content without specialized viewers in a way that still conveyed a semblance of typesetting. The Setext language was formalized for the TidBits newsletter. Both Markdown and reStructuredText were influenced by Setext.

Markdown

Markdown’s primary objective was to create a syntax for plain text that could be easily converted to HTML. Its original implementation is now considered abandonware. As such there is no canonical implementation of Markdown. Several flavors of Markdown now exist, and often have subtle differences between their implementations and syntax.

When composing a Markdown document it is important to know what renders may be used and ensure you use compatible syntax. Generally sticking to Github flavored Markdown will decrease the chance of issues.

reStructuredText

reStructuredText on the other hand was created as the format for Docutils documents. As Docutils is a toolset for generic document processing, reStructuredText is more formalized, and subsequently in a few cases more verbose. However, a document in reStructuredText can easily be converted to a myriad of formats, without concern to the implementation used to parse the document.

Advantages to reStructedText

The greatest advantage to reStructuredText, especially for documentation, is a stronger similarity in the visual representation of the raw text and rendered form. For example, Grid Tables in their raw form are visually similar to their rendered form:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

Compacted to Github flavored Markdown’s table:

| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| git status   | git status     | git status    |
| git diff     | git diff       | git diff      |

Headings in reStructuredText allow for any adornment character to be used to underline the heading in any order. The first character encountered will then be the outermost heading (H1 in HTML speak) then second being the next outermost (H2 in HTML speak) and so on. For example:

Section Title
=============

Section Title
-------------

Section Title
:::::::::::::

Section Title
.............

Section Title
'''''''''''''

Section Title
"""""""""""""

Section Title
^^^^^^^^^^^^^

Section Title
_____________

Section Title
*************

Section Title
+++++++++++++

Section Title
+++++++++++++

Compare this to the Github flavored Markdown that allows up to 6 headings:

# Section Title

## Section Title

### Section Title

#### Section Title

##### Section Title

###### Section Title

NOTE some Markdowns also support underlined titles with = and - only.

Compatibility

It is possible to write in a subset of each such that it is valid syntax in both languages. This gist is a great guide pointing out where similarity exists that can be exploited.

Pragmatism

At the end of the day, either format is better than none. As a general rule of thumb, write documentation in reStructuredText that will be converted into different formats (HTML, man pages, PDF’s) and use Markdown for stylizing git commits or comments (assuming those comments are not harvested for documentation, unless the documentation generator requires a specific Markdown flavor).