1. Preface
reStructuredText and Markdown are two markup languages for describing formatted documents (structure, content, styles, etc.) in text. They can be converted to HTML, PDF, CHM and other target formats through converters.
Using text to describe formatted documents can be traced back to the 1970s, and the representative works are troff and Tex, the users are mainly mathematicians and programmers. In the 1990s, there were more and more Internet users, and people were no longer satisfied with interacting in plain text in forums and emails. Therefore, markup languages began to sprout. For example, BBCode was born in 1998. With the help of markup languages, one can easily express formatted information in bold, italics, colors, lists, etc. in plain text.
There are currently two mainstream markup languages: reStructuredText and Markdown.
2. reStructuredText
reStructuredText appeared in 2002, two years before Markdown. As the official writing language of Python project technical documentation, it was only well-known in the Python circle for most of its birth, and the outside world did not know much about it. It was not until the Sphinx project was released in 2008 that the outside world realized that reStructuredText was also the king of document writing.
Today, some large projects use it for project documentation writing, such as Linux, OpenCV, LLVM etc.
3. Markdown
Markdown appeared in 2004 and is now very popular. The developers are technical writer John Gruber and computer genius Aaron Swartz.
Markdown syntax is very simple, thanks to its late birth, it can fully absorb the various advantages of its predecessors. Markdown is now the default markup language for StackOverflow, Reddit, Github . The currently popular knowledge management software Obsidian supports Markdown very well, and it can even convert notes in Markdown format into mind maps.
4. Compare
Both reStructuredText and Markdown have rich tool chains and practical applications. Which one is better for us to choose? Let's make a comprehensive comparison in terms of simplicity, unity, and scalability.
4.1 Simplicity
Markdown syntax is simpler and easier to read than reStructuredText syntax.
For example the heading:
Markdown heading
# H1 heading ## H2 heading ### H3 heading #### H4 heading ##### H5 heading ###### H6 heading
reStructuredText heading
H1 heading ========== H2 heading ---------- H3 heading ^^^^^^^^^^ H4 heading :::::::::: H5 heading ********** H6 heading ++++++++++
For example the code block:
Markdown code block
```python import random numbers = [] for i in range(10): numbers.append(random.random()) print(numbers) ```
reStructuredText code block
.. code-block:: python import random numbers = \[\] for i in range(10): numbers.append(random.random()) print(numbers)
To be honest, Markdown syntax is much more concise than reStructuredText syntax.
4.2 Uniformity
Markdown has a large number of derivatives, all of which support the most basic Markdown syntax, but each has its own extensions. The main derivatives are: CommonMark, GitHub Flavored Markdown (GFM), Markdown Extra, MultiMarkdown, Pandoc Markdown. Parts of the syntax of the various derivatives are incompatible with each other. Due to technical reasons and historical reasons, the Markdown world cannot be unified in the short term.
This problem does not exist with reStructuredText, which so far has only one specification and one active implementation of the specification --- docutils.
4.3 Extensibility
The reason why there are so many Markdown derivatives is that its core design does not consider the extensibility mechanism. When a new requirement comes, the parser must be modified, so there are so many Markdown islands now.
Instead, reStructuredText is available through role and directive for extensions. By registering, extended functions can be added to reStructuredText, and the core of reStructuredText can call the code of the extended module in a consistent manner. The documentation system Sphinx and the static page generator Pelican are implemented using this extension mechanism.
5. Suggestion
Both reStructuredText and Markdown have their own strengths, and you can choose according to the application scenario.
If you are concerned about functions such as scalability, inter-document reference, and document search, you can choose Sphinx, which fully supports reStructuredText, for document authoring.
If you don't have these requirements, Markdown is a very good choice. For some technical article writers, both languages may need to be mastered.
In addition, Try pandoc! website provides online conversion between reStructuredText and Markdown, and friends who are interested may wish to give it a try.