Remix.run Logo
physicles 4 days 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:

> ![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.

lilyball 4 days ago | parent | next [-]

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.

eviks 4 days ago | parent [-]

No, basically it's "I can remember markdown easier because it's simpler"

CuriouslyC 4 days ago | parent | prev [-]

Lots of people write books in markdown. Obsian/Longform -> Pandoc works well.