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]).
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 · 36m ago
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.
do_not_redeem · 5m ago
Oh I see, you're talking about this:
thisis\ **bold**\ text
thisis\ :strong:`bold`\ text
It's possible, but you're right, definitely more awkward than markdown.
rune-space · 39m ago
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.
ekusiadadus · 17m ago
I’ve never used reST since Markdown has usually been sufficient for me. However, I recently had a situation where Markdown became frustrating to work with.
Indeed, once a document exceeds ten pages, I feel that reST would make managing it much easier.
It would be nice if emphasis and other inline formatting worked smoothly even in agglutinative languages...
bluGill · 1h ago
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 · 1h ago
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.
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!!
This looks kind of useful for creating good contexts about project requirements
physicles · 46m ago
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:
> 
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.
lilyball · 2m ago
Your argument here is basically just "I already know Markdown". Sure, the Markdown image syntax is similar to its hyperlink syntax, so if you know the hyperlink syntax then the image syntax is easy, but the same argument works for reST but even better, the image syntax is the same as any other directive, so if you know how to write a directive then you know how to write an image.
CuriouslyC · 4m ago
Lots of people write books in markdown. Obsian/Longform -> Pandoc works well.
betaby · 1h ago
'asciidoc' is the middle ground.
klodolph · 48m ago
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 · 32m ago
I came here to say this; more complete than markdown, and fewer things require the weird gymnastics of rst.
pavel_lishin · 46m ago
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 · 1h ago
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.
[1] https://talk.commonmark.org/t/foo-works-but-foo-fails/2528
Falsehoods programmers believe about written language: whitespace is used to separate atomic sequences of runes.
It would be nice if emphasis and other inline formatting worked smoothly even in agglutinative languages...
still markdown just isn't powerful enough for anything non trivial.
[1] https://spec.commonmark.org/0.31.2/#html-blocks
https://www.sphinx-needs.com/
But it's overkill for light documentation. Just look at their first example of embedding an image:
> 
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.
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.
Markdown is for the people, almost never full time doc jockeys, who need to WRITE that documentation.