Skip to content(if available)orjump to list(if available)

I Prefer RST to Markdown (2024)

I Prefer RST to Markdown (2024)

14 comments

·August 17, 2025

lifthrasiir

Guaranteed, reST is more feature-complete and extension-friendly, but it is simply unusable for me because it wasn't designed for agglutinative languages like Korean. Markdown is much better in this case (though CommonMark has an annoying edge case [1]).

[1] https://talk.commonmark.org/t/foo-works-but-foo-fails/2528

do_not_redeem

What do you mean not designed for Korean? It's just unicode. If there's some situation where RST isn't parsing inline markup, you can write the role explicitly like this:

  this is **bold** text
  this is :strong:`bold` text

lifthrasiir

reST inline syntaxes are pretty much word-based, which doesn't work very well with agglutinative languages. For example if you want to apply a markup to "이 페이지" in "이 페이지는 ..." (lit. This page in This page is ...), you need to do `*이 페이지*\ 는 ...` AFAIK. That would happen every single time affixes are used, and affixes are extremely frequent in such languages.

rune-space

But you can’t say:

   thisis:strong:`bold`text

Whereas the equivalent is perfectly fine in markdown.

Falsehoods programmers believe about written language: whitespace is used to separate atomic sequences of runes.

bluGill

My only problem with rst is that several useful the extentions are not updated. I have some great rst documentation, but part of that is I importing doxygen, dolphin, and other extentions that are useful but saddly not updated on the same schedule as the main tool. I end up many versions back just because it is all that is compatible.

still markdown just isn't powerful enough for anything non trivial.

lifthrasiir

The original spirit of Markdown was to use HTML elements (or custom elements if you like) for whatever is missing from Markdown. That's surprisingly versatile in hindsight, but the specification didn't fully anticipate what happens to Markdown contents inside such elements. Some implementations supported them, some didn't, some used the `markdown` pseudo-attribute, and so on. And it was even less clear how block syntaxes work inside HTML elements. (CommonMark defines a very lengthy list of rules for them [1].) Markdown could have been extensible... if it did have a sensible specification from beginning.

[1] https://spec.commonmark.org/0.31.2/#html-blocks

acidburnNSA

For books or significant document sets I definitely agree with the author on this. The builtin features for glossary and index are also nice. The extensibility is amazing. Some people are even doing formal requirements and lifecycle management in RST these days!!

https://www.sphinx-needs.com/

4b11b4

This looks kind of useful for creating good contexts about project requirements

physicles

The author wrote a book, for which RST is undoubtedly the better choice. ("I wrote a book in Markdown" would be a surprising headline!)

But it's overkill for light documentation. Just look at their first example of embedding an image:

> ![alttext](example.jpg)

vs

> .. image:: example.jpg

> :alt: alttext

In the first one, it's just the syntax for a hyperlink with ! in front.

In the second one, there are several bits of syntax to remember. We have .. and then whitespace, and not one but two colons after `image`, and it's not `alt:` but `:alt:`.

I don't have to try to remember Markdown syntax, because it's simpler and it's ubiquitous. I type Markdown directly into Slack and Obsidian every day. Most tech-adjacent people know some Markdown.

Many years back a developer on my team decided that all the readmes that live next to source code should be in RST, because it's Better(TM) and we could have nicely formatted generated docs. The result was that a lot less documentation got written, and nobody looked at the generated docs anyway. Eventually we transitioned back.

betaby

'asciidoc' is the middle ground.

klodolph

I think of it less like the middle ground, and more like the best of the three

asciidoc > rst > markdown

It’s just that the available tooling goes the opposite way,

markdown tooling > rst tooling > asciidoc tooling

I end up using HTML for anything serious instead, because it has better tooling support than any of the three, and is also more flexible. It’s just more verbose, which is fine.

aidenn0

I came here to say this; more complete than markdown, and fewer things require the weird gymnastics of rst.

pavel_lishin

These all feel like issues that power-users have, not an issue that lil' ol' me is going to run into while jotting down journal entries, or yelling at people on the internet with emphasis.

ajross

Everyone who works seriously with editing and formatting documentation for presentation prefers RST.

Markdown is for the people, almost never full time doc jockeys, who need to WRITE that documentation.