> reST is also easy to read and write, at least where Markdown is easy to read and write.
It isn't though. It's just a whole lot more annoying. On paper the syntax differences are small, but they make the writing experience so much worse. I wanted to like rST but it just isn't good enough in use.
If rST were actually easy to write and read I would have just used rST instead of creating Markdown.
Re:Why I Prefer RST to Markdown
by __mharrison__ on Wednesday July 31, 2024 @08:35PM
(#41125066)
Except for native Python tools like Jupyter, which have all moved on to md.
(I still like doctests and use them extensively in my books.)
To me, they are largely the same thing, with slight syntax differences, with reST being more readable as it's clearer what any special syntax is about, whereas MD is more concise to type out — you need to learn the special syntax whatever way you slice it.
FWIW, reST was the default for Python "doctests": a wonderful feature that has fallen out of favour for some reason, but has the potential to be your real runnable documentation.
I wouldn't write a book in either, but that's because I am really high on great typesetting — I even had my own set of (Plain) TeX macros to do ToC generation, syntax highlighting, alternative math fonts, support for UTF-8 before eTeX and such when I did write papers and handed in coursework regularly.