Back in summer 2017. I wrote an article explaining why we used Sphinx and reStructuredText for producing teaching materials and not a wiki. In additio

Markdown vs reStructuredText for teaching materials

submited by
Style Pass
2021-08-16 21:30:02

Back in summer 2017. I wrote an article explaining why we used Sphinx and reStructuredText for producing teaching materials and not a wiki. In addition to recommending Sphinx as the solution to use, it was a general praise for generating static HTML files from Markdown or reStructuredText.

This summer I made the conversion of teaching materials from reStructuredText to Markdown. Unfortunately, the automated conversion using Pandoc didn’t quite produce the result I wanted so I ended up cooking my own Python script that converted the specific dialect of reStructuredText that was used for writing the contents of lab.miletic.net and fixing a myriad of inconsistencies in writing style that accumulated over the years.

I personally preferred to write reStructuredText, which I found to be more powerful and better standardized than Markdown (I have heard the same is true about AsciiDoc though I haven’t personally used it). When we forked rDock to start RxDock, reStructuredText and Sphinx were the obvious choice for its documentation. A good argumentation why would a software developer prefer reStructuredText over Markdown for software documentation is given in a very fine article written by Victor Zverovich. He mentions two main advantages, first one being:

reStructuredText provides standard extension mechanisms called directives and roles which make all the difference. For example, you can use the math role to write a mathematical equation (…) and it will be rendered nicely both in HTML using a Javascript library such as MathJax and in PDF via LaTeX or directly. With Markdown you’ll probably have to use MathJax and HTML to PDF conversion which is suboptimal or something like Pandoc to convert to another format first.

Leave a Comment