8 ms·

I Prefer RST to Markdown (2024)

114 points by shlomo_z 1y ago

ajross 1y 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.
cubefox 1y ago
Never mind RST, it would be nice to finally get Markdown and Latex support on Hacker News. Unfortunately the admin seems to be against it.
Firehawke 1y ago
MAME's documentation was moved to Sphinx (and thus RST) a number of years ago. I headed up that project, in fact. There was a significant learning curve getting good output when converting some of the old ASCII charts out of .txt files, but once settled it makes for a much better user experience and it auto-compiles to HTML, PDF, and even EPUB with zero additional effort. I would definitely not want to go to Markdown from RST for technical documentation that's more complex than a Github readme.
mitjam 1y ago
MyST (https://myst-parser.readthedocs.io/en/v0.15.1/index.html https://myst-parser.readthedocs.io/en/v0.15.1/index.html) lets you write in markdown and still use roles and directives provided by Sphinx and its extensions.
- mr_mitm 1y ago
  The author mentions MyST while acknowledging that rst is ugly. I also find MyST to be a sweetspot between comfortable syntax and expressiveness, so I wonder why the author doesn't prefer MyST over rst and common mark.
eviks 1y ago
> On the other hand, the markdown image is hardcoded as a special case in the parser, while the rst image is not. It was added in the exact same way as every other directive in rst: register a handler for the directive, have the handler output a specific kind of node, and then register a renderer for that node for each builder you want. Why not "hardcode" the most common things to be the easiest to use and then still have the option to extend to other protocols? Why "suffer" every time equally instead?
chuckadams 1y ago
The syntax for links in RST is: This is `a link`_ .. _a link: https://foo.com The underscores are required exactly like that. I believe the blank line between is also required. There's also an inline syntax where you use two trailing underscores: This is `an embedded link <http://foo.com>`__ I'd rather write raw HTML.
stonecharioteer 1y ago
I was on that hill too. For years I used Sphinx and Furo to render my blog, which you can still access at https://old.stonecharioteer.com https://old.stonecharioteer.com I like the framework, but it ended up being too in the way. I am not an RST maintainer. I want to blog and get my thoughts out in the world. I split my website to use different subdomains, and most of the posts in that old blog are now in https://tech.stonecharioteer.com https://tech.stonecharioteer.com which is on Hugo now. I used Claude to fix some Css annoyances with the Paper mod theme, and to migrate not only the posts from that old blog but also from the Jekyll blog that predates it. I'm happy with the blog now, it's so out of my way that I can write without trying to figure out how to make Hugo do something like Sphinx-style admonitions. Claude is great for that. What else is there to complain about?
deleted 1y ago
[deleted]
bluGill 1y 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 1y 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. [1] https://spec.commonmark.org/0.31.2/#html-blocks https://spec.commonmark.org/0.31.2/#html-blocks
- chipotle_coyote 1y ago
  > still markdown just isn’t powerful enough for anything non trivial I see this sentiment a lot, and my reaction is always, “Sure it is, with asterisks.” In the past decade I was the primary author of the RethinkDB documentation, a senior technical writer on Bixby’s developer documentation, and am now a contractor working on Minecraft’s developer docs. All of them were large, decidedly non-trivial, and Markdown. Microsoft’s entire learning portal, AFAICT, is in Markdown. And the thing is, each of those systems used a different Markdown processor. My own blog uses one that’s different from all of those. According to HN, I should be spending virtually all my time fighting with all those weird differences and edge cases, but I’m not. I swear. The thing about edge cases is they’re edge cases. I saw a “Markdown torture” document the other day which contained a structure like this: [foo[bar(http://bar.com)](http://foo.com) and proudly proclaimed that different Markdown processors interpret that construct differently. Yes, okay, and? Tell me a use case for that beyond “I want to see how my Markdown processor breaks on that.” The asterisk is that almost any big docs (or even blogging) system built on Markdown has extensions in it, which are usually a function of the template system. Is that part of Markdown? Obviously not. Is it somehow “cheating”? I mean, maybe? At the end of the day, 99% of what I’m writing is still Markdown. I just know that for certain specific constructs I’m going use {{brace-enclosed shortcodes}}, or begin an otherwise-typical Markdown block quote with a special tag like “%tip%” to make it into a tip block. Every system that proclaims it’s better than Markdown because it allows for extensions, well, if you take advantage of that capability, look at you adding site-specific customization just like I’m doing with (checks notes) Markdown. If reStructured Text works better for you, or AsciiDoc, or Org Mode, great! Hell, do it all in DITA, if you’re a masochist. But this whole “this is obviously technically superior to Markdown, which surely no one would ever do real work in, pish tosh” nonsense? We do. It works fine. Sorry.
lifthrasiir 1y ago
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 https://talk.commonmark.org/t/foo-works-but-foo-fails/2528
- do_not_redeem 1y ago
  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
  - rune-space 1y 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.
    - thaumasiotes 1y ago
      > Falsehoods programmers believe about written language: whitespace is used to separate atomic sequences of runes. Really? That isn't just untrue of written language in general. It's untrue of every individual written language in specific. You can't even clearly define what an "atomic sequence of glyphs" is.
      - matja 1y ago
        > You can't even clearly define what an "atomic sequence of glyphs" is. Kinda. Grapheme cluster breaks are defined in Unicode, but they have all the baggage and edge-cases you'd expect from human languages evolving over time, so they can be encoded in as a few as a thousand rules : https://github.com/unicode-org/icu/tree/main/icu4c/source/data/brkitr/rules https://github.com/unicode-org/icu/tree/main/icu4c/source/da...
betaby 1y ago
'asciidoc' is the middle ground.
- klodolph 1y 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 1y ago
  I came here to say this; more complete than markdown, and fewer things require the weird gymnastics of rst.
acidburnNSA 1y ago
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/ https://www.sphinx-needs.com/
- 4b11b4 1y ago
  This looks kind of useful for creating good contexts about project requirements
pavel_lishin 1y 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.
- freehorse 1y ago
  Except if you want to yell at people using different colours and font sizes in a sentence, like in the old forum times, for which markdown is too restrictive.
- lyu07282 1y ago
  On reddit you could really yell at people using a h1 headline in comments, not sure if that's still possible.. hn __is__ more *restricted* sadly
physicles 1y 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.
- CuriouslyC 1y ago
  Lots of people write books in markdown. Obsian/Longform -> Pandoc works well.
- lilyball 1y 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.
  - eviks 1y ago
    No, basically it's "I can remember markdown easier because it's simpler"
ekusiadadus 1y 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...
tambourine_man 1y ago
> Markdown is ubiquitous because it's lightweight and portable… Markdown is ubiquitous because it’s easy for humans to read and write.
- tpoacher 1y ago
  Markdown is ubiquitous because it is easy for humans to read and write AND enough humans used it to make it so. The second part is more important than the first. There could be far better systems which not enough humans used to make ubiquitous. And as far as we know, markdown could be one of the worse ones, but became ubiquitous because it became ubiquitous. cf: MS Windows.
  - tambourine_man 1y ago
    I don't think Windows is an apt comparison. One had huge market forces and distribution channels propelling it, the other is a description page, not even a standard, on Gruber's site. What Gruber got right is that the syntax is beautiful to read, easy to write and powerful enough to be useful, with the optional inline HTML as an escape hatch. It may not seem much, but that's hard to get right.
  - jajuuka 1y ago
    Agreed. Personally I really like asciidoc but hardly anything supports it. Markdown is just everywhere. In all the tools I use and all the most popular tools available. So it's far easier to use when it's so portable. So I only need to remember one set of operators to get the results I want. Even in systems where I don't know which syntax they support. There is a good chance Markdown is will be one of them.
  - deafpolygon 1y ago
    you're both wrong. markdown is ubiquitous thanks to github.
hoherd 1y ago
Does RST have a WYSIWYG editor? Linter that auto-corrects mistakes? Last time I looked neither of these existed. I have a bunch of rst docs that I want to to large edits on, and doing so has been so painful I've decided to migrate to markdown even though it's not as feature rich.
- Firehawke 1y ago
  Not much in the way of WYSIWYG, unfortunately. There've been some VSCode extensions in the past to simplify editing but that's about as good as it gets.
dangus 1y ago
> Now here's how to make an image in rst: .. image:: example.jpg :alt: alttext That is some horrendous syntax. I totally get the author’s power user needs, and the article states plainly that this isn’t for everyone, but there’s gotta be something with power AND earthly syntax, right?
- stock_toaster 1y ago
  Yeah, even asciidoc is nicer than rst!
- chrismorgan 1y ago
  If you’re not accustomed to reStructuredText, it looks dreadful. If you saw it in the context of a larger document that used directives for more things, it’d make more sense. Also the author has very bad taste in having used two spaces of indentation. It should have been three, which makes it significantly less ugly: .. image:: example.jpg :alt: alttext “.. ”: this block is magic. “image::”: directive, type image. “example.jpg”: directive argument, file name. “:alt: alttext” directive option, named alt, value alttext. Rewritten with a completely different sort of syntax, for fun: ┌ IMAGE ─ example.jpg ──┐ │ alt = alttext │ └───────────────────────┘
  - dangus 1y ago
    Yikes, this explanation does not make it better. You’re telling me the indentation convention is three spaces? And “..” is just your “something cool is about to happen” symbol? I’ve been reading through the documentation more and this thing seems insane. That .. symbol is also used for comments!? “Oh if it’s invalid it’s a comment!” No way to make multi-line comments without another ridiculous indentation. The tables are insane, somehow they implemented something worse than markdown. To make a header you need to make a long line of characters as long as your text for some reason. For being a language that’s supposed to be more powerful than markdown and not so HTML-adjacent it sure depends on whitespace a lot. Like, why do literal blocks need be indented? Why do doctest blocks need to end with a blank line? > The handling of the :: marker is smart: > If it occurs as a paragraph of its own, that paragraph is completely left out of the document. > If it is preceded by whitespace, the marker is removed. > If it is preceded by non-whitespace, the marker is replaced by a single colon. lol, a directive that does 3 entirely unrelated things depending on white space. Genius.
Arainach 1y ago
Previously discussed: https://news.ycombinator.com/item?id=41120254 https://news.ycombinator.com/item?id=41120254 Copying my thoughts from there which haven't changed: >To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?" Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant. Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax. I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
- freehorse 1y ago
  I would argue that being harder to extend is actually an advantage of markdown, because it helps with it staying simple and having a relatively agreed upon standard form instead of getting lost in the complexities of different ways to extend it and the different standards this would bring. Being hard to extend means that it is easier to find local optimum rather than exploring the syntax space. Moreover, simple, human readable parsing rules help a lot with reducing cognitive load of the form and focus on the content. Extending a syntax necessarily brings abstractions and more complex parsing rules which would conflict with that goal. In some contexts minimalism and simplicity are features in themselves. For me, I often want to spend my time writing down the stuff I need to write and not play with extensions/logic/configs. I like that it forces me to actually not be able to do sth more complex because I am pretty sure that if I was incentivised to extend it instead, I would end up spending my time with that instead of writing. Markdown is not good for stuff where complex logical structure in the content is important to be represented in the form. In the article it is beyond clear to me why the author did not use markdown for their book, I would be more interested in why they chose RST instead of latex or another language that is more towards the complex end than the minimalistic end. I guess what the author needed was some point in-between, and they found it in RST.
- blenderob 1y ago
jeberle 1y ago
The RST parser is available in only one language, Python. I don't want my content tied to a single language stack, regardless of how good it might be. Markdown parsers exist in any language I care to use.
- xigoi 1y ago
  > Markdown parsers exist in any language I care to use. Except each one actually parses a slightly different language. https://git.sr.ht/~xigoi/markdown-monster/blob/master/monster.md https://git.sr.ht/~xigoi/markdown-monster/blob/master/monste...
  - kazinator 1y ago
    So for instance, your git repo README.md that looks nice on your self-hosted CGIT site might not look right if someone clones your stuff to GitHub.
freeopinion 1y ago
I'm interested in people's opinion of typst's ease of writing and reading when limited to the simple types of documents for which people use Markdown. Do you think it makes easy things easy and complex things possible?
- blenderob 1y ago
  I'd have loved to use Typst but all journals I submit to ask for LaTeX. And it isn't just LaTeX they ask. They ask LaTeX with specific documentclasses. The mainstream academia and journals have so much tooling built around LaTeX and documentclasses and they have so much inertia that I am very pessimistic that Typst will ever get any "market share" in mainstream publishing!
  - freeopinion 1y ago
    Typst is made for the same target a Tex. Here I am asking if it is a reasonable replacement for Markdown or ReST in a target I don't think it was originally intended for. It would be interesting if the most popular forges enabled typst rendering for things like READMEs.
- tornikeo 1y ago
  Typst is almost as easy as markdown, but my only gripe is with the web editor app: the inability to insert links quickly, i.e. with a copy-paste shortcut.
- commandersaki 1y ago
  Would gladly use typst over md, rst, html, latex.
cycomanic 1y ago
I have run into frustrations with Markdown and even had a short "I do everything in RST" phase. At some point during that phase I tried org mode and it's better than both, it is easier to read/write than RST, and better for large documents than Markdown. Unfortunately it doesn't get accepted in as many places as Markdown.
lawn 1y ago
As a compromise, I prefer Djot to markdown. It's basically markdown, but made to be easier to parse with explicit support for nice addons such as tables, divs, and attributes.
- aledue 1y ago
  Me too. It's a shame though that it both feels unfinished and evolves at a glacial speed. https://djot.net https://djot.net
nialv7 1y ago
Uh, why haven't we drilled it into people's brains that regex cannot be used to parse matching parentheses/brackets?
arkt8 1y ago
The only change I do and expect of markdown is enforce blank lines as separators after *any* header and blocks and use the `*` as formatting. Everything can be extended with fenced block. RST is a lot more difficult to write and much more "groffy".
jeroenhd 1y ago
I can see the advantages RST offers in term of HTML generation, but whenever I've needed to work with custom blocks like that, I've always just written HTML. I'm not sure if <img src="file.jpg" alt="alt text"/> is less readable than .. image:: file.jpg :alt: Alt text HTML5 allows for leaving certain tags unclosed (such as <li>, or <head> or even <p>) to such an extent that I find many template languages to not be worth the effort of their complex syntax. Sure, there are three or four lines here that you can omit using RST or markdown: <!doctype html> <html lang="en"> <head> <title>My blog page</title> <body> <h1>Welcome to my blog</h1> <p>This is a bunch of text. Feel free to stuff newlines here. <p>This is also a bunch of text <p>Here's a list just for fun: <ol> <li>This is the first item! <li>This is the second one! <li>Boom, a third! </ol> <p>Have an image: <img src="filename.jpg" alt="alt text goes here"> But is having to wrap a list in <ol> and closing the <title> really that bad? Automatically generating an index and such is nice, but five lines of Javascript can do the same. Plus, you don't need to run a second tool to "process" your input. I generally use Markdown as a standardised way to format text that will probably be read in plaintext by other people, but when it comes to formatting documents, I don't see the point of most complex template languages.
- tpoacher 1y ago
  Same. I have a couple of nice html templates (with locally-defined css and mathjax styling), and I now take all my notes directly in html in nano. Once you've written a couple of documents, the usual tags become muscle memory and are no more of a bother to write than markdown. I've even created a couple of nano macros to automate some of the process. "But it's not readable like markdown" you might say. Well. This might be true of 'some' html, especially autogenerated stuff, but the stuff I write is totally readable. Once you settle on some meaningful indentation and tag presentation conventions, readability is not a problem. We're talking about plain html documents, after all, not complex websites. The subset of html tags you'll need is generally very small and largely unintrusive. I could even go a step further and say, my HTML is as readable as this guy's rST, but this guy's generated HTML code is far worse than how my direct HTML would have looked.
- aitchnyu 1y ago

114 points by shlomo_z 1y 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.

cubefox 1y ago

Never mind RST, it would be nice to finally get Markdown and Latex support on Hacker News. Unfortunately the admin seems to be against it.

Firehawke 1y ago

MAME's documentation was moved to Sphinx (and thus RST) a number of years ago. I headed up that project, in fact. There was a significant learning curve getting good output when converting some of the old ASCII charts out of .txt files, but once settled it makes for a much better user experience and it auto-compiles to HTML, PDF, and even EPUB with zero additional effort. I would definitely not want to go to Markdown from RST for technical documentation that's more complex than a Github readme.

mitjam 1y ago

MyST (https://myst-parser.readthedocs.io/en/v0.15.1/index.html https://myst-parser.readthedocs.io/en/v0.15.1/index.html) lets you write in markdown and still use roles and directives provided by Sphinx and its extensions.

mr_mitm 1y ago
The author mentions MyST while acknowledging that rst is ugly. I also find MyST to be a sweetspot between comfortable syntax and expressiveness, so I wonder why the author doesn't prefer MyST over rst and common mark.

eviks 1y ago

> On the other hand, the markdown image is hardcoded as a special case in the parser, while the rst image is not. It was added in the exact same way as every other directive in rst: register a handler for the directive, have the handler output a specific kind of node, and then register a renderer for that node for each builder you want. Why not "hardcode" the most common things to be the easiest to use and then still have the option to extend to other protocols? Why "suffer" every time equally instead?

chuckadams 1y ago

The syntax for links in RST is: This is `a link`_ .. _a link: https://foo.com The underscores are required exactly like that. I believe the blank line between is also required. There's also an inline syntax where you use two trailing underscores: This is `an embedded link <http://foo.com>`__ I'd rather write raw HTML.

stonecharioteer 1y ago

I was on that hill too. For years I used Sphinx and Furo to render my blog, which you can still access at https://old.stonecharioteer.com https://old.stonecharioteer.com I like the framework, but it ended up being too in the way. I am not an RST maintainer. I want to blog and get my thoughts out in the world. I split my website to use different subdomains, and most of the posts in that old blog are now in https://tech.stonecharioteer.com https://tech.stonecharioteer.com which is on Hugo now. I used Claude to fix some Css annoyances with the Paper mod theme, and to migrate not only the posts from that old blog but also from the Jekyll blog that predates it. I'm happy with the blog now, it's so out of my way that I can write without trying to figure out how to make Hugo do something like Sphinx-style admonitions. Claude is great for that. What else is there to complain about?

deleted 1y ago

[deleted]

bluGill 1y 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 1y 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. [1] https://spec.commonmark.org/0.31.2/#html-blocks https://spec.commonmark.org/0.31.2/#html-blocks
chipotle_coyote 1y ago
> still markdown just isn’t powerful enough for anything non trivial I see this sentiment a lot, and my reaction is always, “Sure it is, with asterisks.” In the past decade I was the primary author of the RethinkDB documentation, a senior technical writer on Bixby’s developer documentation, and am now a contractor working on Minecraft’s developer docs. All of them were large, decidedly non-trivial, and Markdown. Microsoft’s entire learning portal, AFAICT, is in Markdown. And the thing is, each of those systems used a different Markdown processor. My own blog uses one that’s different from all of those. According to HN, I should be spending virtually all my time fighting with all those weird differences and edge cases, but I’m not. I swear. The thing about edge cases is they’re edge cases. I saw a “Markdown torture” document the other day which contained a structure like this: [foo[bar(http://bar.com)](http://foo.com) and proudly proclaimed that different Markdown processors interpret that construct differently. Yes, okay, and? Tell me a use case for that beyond “I want to see how my Markdown processor breaks on that.” The asterisk is that almost any big docs (or even blogging) system built on Markdown has extensions in it, which are usually a function of the template system. Is that part of Markdown? Obviously not. Is it somehow “cheating”? I mean, maybe? At the end of the day, 99% of what I’m writing is still Markdown. I just know that for certain specific constructs I’m going use {{brace-enclosed shortcodes}}, or begin an otherwise-typical Markdown block quote with a special tag like “%tip%” to make it into a tip block. Every system that proclaims it’s better than Markdown because it allows for extensions, well, if you take advantage of that capability, look at you adding site-specific customization just like I’m doing with (checks notes) Markdown. If reStructured Text works better for you, or AsciiDoc, or Org Mode, great! Hell, do it all in DITA, if you’re a masochist. But this whole “this is obviously technically superior to Markdown, which surely no one would ever do real work in, pish tosh” nonsense? We do. It works fine. Sorry.

lifthrasiir 1y ago

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 https://talk.commonmark.org/t/foo-works-but-foo-fails/2528

do_not_redeem 1y ago
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
- rune-space 1y 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.
  - thaumasiotes 1y ago
    > Falsehoods programmers believe about written language: whitespace is used to separate atomic sequences of runes. Really? That isn't just untrue of written language in general. It's untrue of every individual written language in specific. You can't even clearly define what an "atomic sequence of glyphs" is.
    - matja 1y ago
      > You can't even clearly define what an "atomic sequence of glyphs" is. Kinda. Grapheme cluster breaks are defined in Unicode, but they have all the baggage and edge-cases you'd expect from human languages evolving over time, so they can be encoded in as a few as a thousand rules : https://github.com/unicode-org/icu/tree/main/icu4c/source/data/brkitr/rules https://github.com/unicode-org/icu/tree/main/icu4c/source/da...

betaby 1y ago

'asciidoc' is the middle ground.

klodolph 1y 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 1y ago
I came here to say this; more complete than markdown, and fewer things require the weird gymnastics of rst.

acidburnNSA 1y ago

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/ https://www.sphinx-needs.com/

4b11b4 1y ago
This looks kind of useful for creating good contexts about project requirements

pavel_lishin 1y 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.

freehorse 1y ago
Except if you want to yell at people using different colours and font sizes in a sentence, like in the old forum times, for which markdown is too restrictive.
lyu07282 1y ago
On reddit you could really yell at people using a h1 headline in comments, not sure if that's still possible.. hn __is__ more *restricted* sadly

physicles 1y 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.

CuriouslyC 1y ago
Lots of people write books in markdown. Obsian/Longform -> Pandoc works well.
lilyball 1y 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.
- eviks 1y ago
  No, basically it's "I can remember markdown easier because it's simpler"

ekusiadadus 1y 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...

tambourine_man 1y ago

> Markdown is ubiquitous because it's lightweight and portable… Markdown is ubiquitous because it’s easy for humans to read and write.

tpoacher 1y ago
Markdown is ubiquitous because it is easy for humans to read and write AND enough humans used it to make it so. The second part is more important than the first. There could be far better systems which not enough humans used to make ubiquitous. And as far as we know, markdown could be one of the worse ones, but became ubiquitous because it became ubiquitous. cf: MS Windows.
- tambourine_man 1y ago
  I don't think Windows is an apt comparison. One had huge market forces and distribution channels propelling it, the other is a description page, not even a standard, on Gruber's site. What Gruber got right is that the syntax is beautiful to read, easy to write and powerful enough to be useful, with the optional inline HTML as an escape hatch. It may not seem much, but that's hard to get right.
- jajuuka 1y ago
  Agreed. Personally I really like asciidoc but hardly anything supports it. Markdown is just everywhere. In all the tools I use and all the most popular tools available. So it's far easier to use when it's so portable. So I only need to remember one set of operators to get the results I want. Even in systems where I don't know which syntax they support. There is a good chance Markdown is will be one of them.
- deafpolygon 1y ago
  you're both wrong. markdown is ubiquitous thanks to github.

hoherd 1y ago

Does RST have a WYSIWYG editor? Linter that auto-corrects mistakes? Last time I looked neither of these existed. I have a bunch of rst docs that I want to to large edits on, and doing so has been so painful I've decided to migrate to markdown even though it's not as feature rich.

Firehawke 1y ago
Not much in the way of WYSIWYG, unfortunately. There've been some VSCode extensions in the past to simplify editing but that's about as good as it gets.

dangus 1y ago

> Now here's how to make an image in rst: .. image:: example.jpg :alt: alttext That is some horrendous syntax. I totally get the author’s power user needs, and the article states plainly that this isn’t for everyone, but there’s gotta be something with power AND earthly syntax, right?

stock_toaster 1y ago
Yeah, even asciidoc is nicer than rst!
chrismorgan 1y ago
If you’re not accustomed to reStructuredText, it looks dreadful. If you saw it in the context of a larger document that used directives for more things, it’d make more sense. Also the author has very bad taste in having used two spaces of indentation. It should have been three, which makes it significantly less ugly: .. image:: example.jpg :alt: alttext “.. ”: this block is magic. “image::”: directive, type image. “example.jpg”: directive argument, file name. “:alt: alttext” directive option, named alt, value alttext. Rewritten with a completely different sort of syntax, for fun: ┌ IMAGE ─ example.jpg ──┐ │ alt = alttext │ └───────────────────────┘
- dangus 1y ago
  Yikes, this explanation does not make it better. You’re telling me the indentation convention is three spaces? And “..” is just your “something cool is about to happen” symbol? I’ve been reading through the documentation more and this thing seems insane. That .. symbol is also used for comments!? “Oh if it’s invalid it’s a comment!” No way to make multi-line comments without another ridiculous indentation. The tables are insane, somehow they implemented something worse than markdown. To make a header you need to make a long line of characters as long as your text for some reason. For being a language that’s supposed to be more powerful than markdown and not so HTML-adjacent it sure depends on whitespace a lot. Like, why do literal blocks need be indented? Why do doctest blocks need to end with a blank line? > The handling of the :: marker is smart: > If it occurs as a paragraph of its own, that paragraph is completely left out of the document. > If it is preceded by whitespace, the marker is removed. > If it is preceded by non-whitespace, the marker is replaced by a single colon. lol, a directive that does 3 entirely unrelated things depending on white space. Genius.

Arainach 1y ago

Previously discussed: https://news.ycombinator.com/item?id=41120254 https://news.ycombinator.com/item?id=41120254 Copying my thoughts from there which haven't changed: >To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?" Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant. Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax. I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.

freehorse 1y ago
I would argue that being harder to extend is actually an advantage of markdown, because it helps with it staying simple and having a relatively agreed upon standard form instead of getting lost in the complexities of different ways to extend it and the different standards this would bring. Being hard to extend means that it is easier to find local optimum rather than exploring the syntax space. Moreover, simple, human readable parsing rules help a lot with reducing cognitive load of the form and focus on the content. Extending a syntax necessarily brings abstractions and more complex parsing rules which would conflict with that goal. In some contexts minimalism and simplicity are features in themselves. For me, I often want to spend my time writing down the stuff I need to write and not play with extensions/logic/configs. I like that it forces me to actually not be able to do sth more complex because I am pretty sure that if I was incentivised to extend it instead, I would end up spending my time with that instead of writing. Markdown is not good for stuff where complex logical structure in the content is important to be represented in the form. In the article it is beyond clear to me why the author did not use markdown for their book, I would be more interested in why they chose RST instead of latex or another language that is more towards the complex end than the minimalistic end. I guess what the author needed was some point in-between, and they found it in RST.
blenderob 1y ago

jeberle 1y ago

The RST parser is available in only one language, Python. I don't want my content tied to a single language stack, regardless of how good it might be. Markdown parsers exist in any language I care to use.

xigoi 1y ago
> Markdown parsers exist in any language I care to use. Except each one actually parses a slightly different language. https://git.sr.ht/~xigoi/markdown-monster/blob/master/monster.md https://git.sr.ht/~xigoi/markdown-monster/blob/master/monste...
- kazinator 1y ago
  So for instance, your git repo README.md that looks nice on your self-hosted CGIT site might not look right if someone clones your stuff to GitHub.

freeopinion 1y ago

I'm interested in people's opinion of typst's ease of writing and reading when limited to the simple types of documents for which people use Markdown. Do you think it makes easy things easy and complex things possible?

blenderob 1y ago
I'd have loved to use Typst but all journals I submit to ask for LaTeX. And it isn't just LaTeX they ask. They ask LaTeX with specific documentclasses. The mainstream academia and journals have so much tooling built around LaTeX and documentclasses and they have so much inertia that I am very pessimistic that Typst will ever get any "market share" in mainstream publishing!
- freeopinion 1y ago
  Typst is made for the same target a Tex. Here I am asking if it is a reasonable replacement for Markdown or ReST in a target I don't think it was originally intended for. It would be interesting if the most popular forges enabled typst rendering for things like READMEs.
tornikeo 1y ago
Typst is almost as easy as markdown, but my only gripe is with the web editor app: the inability to insert links quickly, i.e. with a copy-paste shortcut.
commandersaki 1y ago
Would gladly use typst over md, rst, html, latex.

cycomanic 1y ago

I have run into frustrations with Markdown and even had a short "I do everything in RST" phase. At some point during that phase I tried org mode and it's better than both, it is easier to read/write than RST, and better for large documents than Markdown. Unfortunately it doesn't get accepted in as many places as Markdown.

lawn 1y ago

As a compromise, I prefer Djot to markdown. It's basically markdown, but made to be easier to parse with explicit support for nice addons such as tables, divs, and attributes.

aledue 1y ago
Me too. It's a shame though that it both feels unfinished and evolves at a glacial speed. https://djot.net https://djot.net

nialv7 1y ago

Uh, why haven't we drilled it into people's brains that regex cannot be used to parse matching parentheses/brackets?

arkt8 1y ago

The only change I do and expect of markdown is enforce blank lines as separators after *any* header and blocks and use the `*` as formatting. Everything can be extended with fenced block. RST is a lot more difficult to write and much more "groffy".

jeroenhd 1y ago

I can see the advantages RST offers in term of HTML generation, but whenever I've needed to work with custom blocks like that, I've always just written HTML. I'm not sure if <img src="file.jpg" alt="alt text"/> is less readable than .. image:: file.jpg :alt: Alt text HTML5 allows for leaving certain tags unclosed (such as <li>, or <head> or even <p>) to such an extent that I find many template languages to not be worth the effort of their complex syntax. Sure, there are three or four lines here that you can omit using RST or markdown: <!doctype html> <html lang="en"> <head> <title>My blog page</title> <body> <h1>Welcome to my blog</h1> <p>This is a bunch of text. Feel free to stuff newlines here. <p>This is also a bunch of text <p>Here's a list just for fun: <ol> <li>This is the first item! <li>This is the second one! <li>Boom, a third! </ol> <p>Have an image: <img src="filename.jpg" alt="alt text goes here"> But is having to wrap a list in <ol> and closing the <title> really that bad? Automatically generating an index and such is nice, but five lines of Javascript can do the same. Plus, you don't need to run a second tool to "process" your input. I generally use Markdown as a standardised way to format text that will probably be read in plaintext by other people, but when it comes to formatting documents, I don't see the point of most complex template languages.

tpoacher 1y ago
Same. I have a couple of nice html templates (with locally-defined css and mathjax styling), and I now take all my notes directly in html in nano. Once you've written a couple of documents, the usual tags become muscle memory and are no more of a bother to write than markdown. I've even created a couple of nano macros to automate some of the process. "But it's not readable like markdown" you might say. Well. This might be true of 'some' html, especially autogenerated stuff, but the stuff I write is totally readable. Once you settle on some meaningful indentation and tag presentation conventions, readability is not a problem. We're talking about plain html documents, after all, not complex websites. The subset of html tags you'll need is generally very small and largely unintrusive. I could even go a step further and say, my HTML is as readable as this guy's rST, but this guy's generated HTML code is far worse than how my direct HTML would have looked.
aitchnyu 1y ago