July 31, 2024
Why I prefer rST to markdown
I will never stop dying on this hill
I just published a new version of Logic for Programmers! v0.2 has epub support, content on constraint solving and formal specification, and more! Get it here.
This is my second book written with Sphinx, after the new Learn TLA+. Sphinx uses a peculiar markup called reStructured Text (rST), which has a steeper learning curve than markdown. I only switched to it after writing a couple of books in markdown and deciding I needed something better. So I want to talk about why rst was that something.
Why rst is better
The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree.
It's easiest to see this with a comparison. Here's how to make an image in markdown:
Technically, you don't even need a parser for this. You just need a regex to transform it into 
. Most modern markdown engines do parse this into an intermediate representation, but the essence of markdown is that it's a lightweight html notation.
... continue reading