Why I Prefer RST to Markdown

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

Context: I've been a technical writer for ~12 years. I actually started out my career migrating a startup's docs from Word to Sphinx. Then I did a lot of time on Google's proprietary CMS/platform for developer docs. Then a few years on Eleventy-based sites. For the last two years I've been back on a Sphinx-based site (pigweed.dev). I've also done some odd jobs for readme.com-based startups and have dabbled in Docusaurus, Astro, and Hugo.

reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great. I.e. the strengths of Sphinx far outweigh the weaknesses of reST. For big, professional docs sites (+100 pages, +10 contributors) I have pretty strong opinions that Sphinx is probably the most responsible choice, long-term.

> The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree.

Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed). A teammate of mine on Pigweed recently created a shortcut for linking to bugs consistently. You type :bug:`59385981` and the link gets transformed into https://pwbug.dev/59385981. If we ever need to mass-migrate all of our bug links, it's now trivial. Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html

The other thing that Sphinx excels at: well-defined extension and theme APIs. It's not exactly easy to build extensions or themes, but lots of people have figured it out (including me). There's a pretty rich ecosystem of extensions and themes on PyPI.

Lately I've been calling Sphinx the sleeping giant of docs systems. It's already pretty great and with a little concerted effort I think we can collectively make it absolutely phenomenal. The upstream Sphinx repo now has a GitHub Discussions section that gets a little traffic; a lot of us seem to congregrate on the #sphinx channel in the Write The Docs Slack.

> markdown is a lightweight representation of html

This is my main problem with the article, as this is decidedly incorrect.

Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like.

True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard.

[0] https://daringfireball.net/projects/markdown/

> markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree

To me, the whole point of markdown is to allow you to do simple things faster than writing raw HTML, but with the ability to intersperse raw HTML when needed.

In projects where I've needed the power of RST over markdown, I've felt more comfortable just writing raw HTML directly.

I was looking at RST as an answer for a documentation system with similar complexity to the system he's building and an intense need to mark stuff up with definite semantics, both in the case of capturing structures in the RST file in a database and mixing database results into the content.

Two problems I had were: (1) common with a lot of systems, the RST tools don't contain an RST unparser. I really wanted to be able to generate RST files automatically by merging content from other RST files and other sources and working with them via a document API. The RST tools don't support that. (2) The RST tools expect a certain defined set of blocks for a particular document; it would be very possible for a system to represent blocks in a generic way which would make possible tools that can transform documents without necessarily knowing the definitions of blocks inside it.

These are problems w/ the tools, not problems with RST itself but every time I'm forced to strip my code back to the walls is an opportunity to think about some other markup system such as something HTML-based.

A few years ago I wrote up some notes on the subset of reStructuredText that's worth committing to memory: https://simonwillison.net/2018/Aug/25/restructuredtext/

I've started using MyST for my more recent projects, which gives me the features I care about from reStructuredText - references and table of contents - but lets me use markdown syntax, which is easier for contributors.

I don't mean to hijack a conversation about ReStructuredText, but if you're looking for a markup language that gives you more than Markdown, look at AsciiDoc rather than ReStructuredText. I have written technical documentation using all three for years and AsciiDoc is superior to both ReStructuredText and Markdown, in my opinion.

For example, Markdown's and ReStructuredText's support for tables is cumbersome to say the least. AsciiDoc's table formatting is much easier to read, write, and maintain, and AsciiDoc tables are more robust, supporting headers, captions, custom dimensions for tables/rows, and complex formatting within tables.

Some other benefits include:

• A single, standardized format where Markdown and ReStructuredText do not (in other words, there are no "flavors" like you have in Markdown).

• Concise and readable syntax.

• A more gradual learning curve that ReStructuredText (probably due to its consistency and excellent documentation).

• Superior styling options for your output.

• A superior toolchain to the other two markup languages.

• A rich set of built-in documentation features, so you rarely have to rely on third-party plugins.

AsciiDoc was designed from the ground up for technical documentation, whereas the other two get shoehorned into that role.

Having worked extensively with all three, I can't recommend AsciiDoc highly enough.

I’ve done this thing a few times where I have a nice layout of about 5-10 pages of markdown docs, themselves rendered from more dynamic jinja templates, and feel that life is pretty good. Looks great, got a real build process for auto docs, but too big for a monolithic GitHub readme. Now the pain starts.

GitHub’s own docs for project pages don’t work. Do I need a .nojekyl file, are gh-pages branches still required? Is there a config error in the repo or did changes just not prop? I guess I’ll try actions. Fast forward a few hours and this is getting unreasonable, haven’t looked at read the docs in a while, let’s see if that works. Ok it’s being weird and wants sphinx maybe, let’s get sphinx to work with markdown, ok cool. The build works but the page width is broken after deployment even though I can’t reproduce on my machine so it must be the ads injection on the community tier.

I know all this is working fine for lots of projects and have done it myself in the past. It works after it’s working. But it’s all so unbelievably fiddly. Bottom line, Markdown vs Rst isn’t even a choice/pain point on my radar, it’s more down to finding that good fit for medium sized docs projects / static hosting.

I think commenters are missing that the author is talking about this in the context of typesetting their own book. They aren't claiming that rST is better than Markdown in the general case; in general, Markdown's simplicity is a reason why it is so widely used. But that's not what the author is talking about.

It's funny how people are commenting as if reST was created as a competitor to MarkDown: it's actually quite the opposite. reST was a 2002 evolution on StructuredText from even earlier, and MD was first publicized in 2004.

They've got extremely similar goals, and for the most basic text, both read and write like plain text too. And it was obviously a time when this thing simply became a thing everybody desired, so many "formats" appeared.

Why did MD win has — IMO — nothing to do with how it's "simpler" or "more readable" — they are largely interchangeable for anything that's easily represented with whitespaces in pure ASCII.

Or does someone claim that the following is unreadable gibberish that they need a parser for?

  The best friends
  ================

  ``markdown`` and ``reST`` are two formats that *largely* aim to achieve the same goals:

  * Be simple to read without any parser
  * Be quick and simple to type out

I really, really don't see how the Markdown variant of the above is better in any way (note that I am not saying that reST is better either)? It's mostly the weirdness of history that has one prevail over the other, but both are good enough for their core goals.

If it's a matter of preference then whatever.

We had our documentation in asciidoc and it was awesome to write. We migrated to RTD/Sphinx/rST mainly for 1) better handling of i18n and 2) better handling of multiple-version-documentation (switching between versions)... and I loath rST every day. It's syntax is just abysmally awful and the tooling sucks (seriously, it's not just bad... it sucks!).

Nowadays there is antora but still - i18n is still a problem…

And markdown - as a simple tool to add some simple and basic formatting is just awesome and it's easily readable even if you don't have parser and end up having to read plaintext…

I would strongly recommend using Asciidoc over Restructured Text. Even though Asciidoctor is written in Ruby which IMO is much worse than even Python, the actual RST codebase is a total incomprehensible mess. You can extend it with custom processing etc, but... fuck, I really want to never have to do that again.

Asciidoc just seems to be much higher quality in general.

Isn’t this just a case of different tools for different jobs (or the right tool for the right job)? Rst clearly has some advantages for this use case but, at least for me, markdown is much faster and clearer to understand when jotting down my daily notes.

I like writing markdown because it is so simple, but I agree with the author that it is too simple for more advanced stuff.

But at the same time, I find the writing experience for more advanced stuff too poor. The author talks about references, but do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?

That’s what would make me take the plunge to a more advanced system.

Markdown:

    ![alttext](example.jpg)

RST:

    .. image:: example.jpg
      :alt: alttext

The author prefers RST because:

    ... you can extend Sphinx with new text objects!
    Say you that instead of an <image>, you want
    a <figure> with a <figcaption> ...

What I would do:

        ![alttext](example.jpg)[caption]

And write a renderer which supports this syntax to create a figure with a figcaption. A markdown renderer is simple enough to write your own or extend an existing one.

The thing I like about markdown is that it's very readable as just a raw format. With the bonus that it's easily converted to HTML. But it doesn't need to be converted to HTML.

I guess this sort of falls under the "But I hate the syntax" section of the article, but I don't think it quite gets the point. I can look at a Markdown file and read or write it without even really thinking. Which is not really the case with rST (or even HTML, for that matter).

I lament the lack of rST support in much of modern tooling.

I'm reminded of all of the alternate worlds that didn't quite come to fruition, but could have (Lisp, Smalltalk, BeOS, etc.).

Any sufficiently complicated lightweight markup format contains an ad-hoc, informally-specified, bug-ridden, and only slightly easier to use implementation of half of either DocBook or TeX.

Markdown has a great linter in markdownlint. When I worked in rST, I found the syntax to be super extensible, and tables much easier to write (list tables! amazing!) but without an effective linter, writing in rST was consistently painful.

Whitespace has meaning, so I had to set up all sorts of indent highlights and dots for each space in my IDE to try to avoid screwing up the syntax inadvertently.

rst-lint and others exist, but don't seem to be maintained, and didn't seem to have documentation about how to add support for custom directives (which are definitely one of the key advantages of rST).

I'd write in rST again, but without an effective linter to stop me from making easy mistakes, I wouldn't be happy about it.

I wrote my books for years with rST. (I also used Asciidoc, and one publisher wanted me to use Word.) Recently, I migrated all of my tooling to Markdown.

It turned out that no single markup language supported all of the features required to make physical books, so I would need custom tooling regardless. The rest of the world was moving onto MD, and even though I'm a huge Python fan, rST is painful, and writing tooling with it is even worse. (I also have commit rights for docutils.)

I don't regret my choice one bit. It has made my life much easier, and I can work much faster today.

I thank the author for explaining their reasoning. I still disagree, but I appreciated reading the argument.

Apart from the ugliness of the syntax from a devex perspective, I think one of the big advantages of Markdown is that it's highly readable even without being interpreted, which rST is not. So if you have a markdown document and no markdown interpreter, an average person can still make more or less perfect sense of the contents, including the hierarchy and emphasis.

The one-line summary is:

> I think Restructured Text is better for writing books than Markdown.

That would be a better title.

Wasn't reStructuredText the one where you can't make text a link if any of it is bold/italic/monospaced? IIRC, nesting of inline markup is generally not possible. It works in Markdown…

Rst is technically vastly superior to MD. Yet I predict that MD will prevail. VHS style.

I hugely prefer to write in RST, but as soon as I'm not alone we always switch to MD, given enough coworkers.

Sphinx + markdown (Myst) is a nice middle ground here I think, with the sphinx directives implemented as code blocks.

A lot of lightweight markup languages get the basics right (except MediaWiki). Then eventually when it comes to making extensions—and especially if it is supposed to be terse, or look it—people get into the game of strategizing ascii symbol use (maybe `!` for images, maybe `@` for a figure).

At some point (and Rst[1] has a tendency to look like this, but only a little) it can start to look like some alternative, less regular markup language. Maybe you just use more backticks rather than angle “brackets”. Or maybe you have (like previously stated) marshalled all the ascii symbols so that all the common stuff can have a terse representation.

Maybe they should just make a regular-looking markup for the unusual cases/user defined things. They could do something like Pollen with its Latex[1] syntax inspiration.

[1] Initial caps for proper nouns

Personally, besides it being a nice format, I use Markdown to honor Aaron Swartz.

I use Markdown constantly, every single day, and I have tried multiple times to switch to RST and failed. Ultimately the reason Markdown works the best for me is that it gets out of my way. I can just type, I don't have to invest significant effort in formatting structures and can just write. This makes Markdown ideal for my primary use case, which is note-taking live during meetings, and because I already use it there, I also use it for writing blog posts, documentation, and most other document writing purposes. I will freely acknowledge RST is better for writing documentation and formal structured documentation, but the learning curve/barrier for RST is enough higher than Markdown, that it's not worth it for me to use both systems.

To me rST targets such a narrow middle band of scenarios that I can't see any compelling reason to use it. For simple documents where Markdown is enough, I'll use that, and if I need more layout configuration and control I'll use LaTeX or HTML. What is rST for?

> it's that simple markdown is exceptionally bad. It doesn't have a uniform extension syntax or native support for pre-render transforms.

I feel like "simple markdown" is a straw man here. If you're doing anything complex with markdown you're going to pick a flavor and learn it. Many flavors of markdown can do the things described.

Here's a Hugo figure which looks easier to understand than the "ugly rST" equivalent: https://gohugo.io/content-management/shortcodes/#embedded-sh...

Another good documentation choices is Racket’s scribble^1. I like that you can embed Racket code directly into the text, and the language oriented programming of Racket means the syntax is more ergonomic than other systems. There is also pollen^2 but that is more set up for online books by default

1. https://docs.racket-lang.org/scribble/

2. https://docs.racket-lang.org/pollen/

I was thinking of how to setup a simple static blog without the baggage of a full-blow framework. Of course, I'd be re-inventing the wheel, but at least it'll make sense to me, personally.

What I came up with:

* Each page gets its own folder.

* An optional METADATA file in each folder has stuff like the type of the page (blog post, photo gallery, code listing).

* The index file can be in Markdown or rST or something. I'd just branch to a different parser based on the file name suffix.

This is simple and lets me evolve the blog over time.

For a personal blog, an ideal mix might be just branching to a different HTML converter based on the

> When I gush about rST to other programmers, this is the objection I hear the most: it's ugly. 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?

I like my Markdown documents to be nicely readable in source form. Because that's what I'm editing so being readable helps, and it's also what I read most of the time.

I don't think Markdown is perfect. I have gripes. But it's "good enough", and damn near everywhere already so it's "in the fingers", so to speak.

> Markdown doesn't have a uniform extension syntax or native support for pre-render transforms.

Well no, but "Markdown" is also a standard with more implementations you can shake a stick at, whereas most of the alternates mentioned n the article are basically just a program written in $lang, and that's it. I think some do have a spec document, but also don't really have complete alternative implementations, so it doesn't really matter.

And I get the point; for my own website I have this ... piece of art ... to transform some of the HTML: https://github.com/arp242/arp242.net/blob/master/_plugins/ma...

On one hand: eww. On the other hand: it's not strictly needed, hard to do cross-platform, and has been working fine for a long time now. So whatever.

The author claims that RST is nice because it's extensible, but as someone who's written some Sphinx extensions, I can tell you that extending RST is not as pleasant of a task as the author makes it out to be. I don't really know what it's like in Markdown world, but the underlying tools (Sphinx and docutils) are very difficult to work with, and make many implicit assumptions that make certain things difficult or impossible.

While I definitely understand what the author is saying, the reality is that, for the majority of writing developers will be doing, having something that is easy-to-produce and easy-to-consume is paramount. There are tons of more powerful and flexible options than Markdown, but none that let you create a document that is both computer- and human-readable quite as quickly. Documentation that is written is better than documentation that isn't.

I don't understand the argument for rST. If you need more control than Markdown can deliver, then write your stuff in HTML to begin with.

I have written a ton of documents in plain HTML, including slide decks, documentation for customers, reports for customers, a blog. I have not written a book yet. If I were to write a book, I would use LaTeX because then the typographic fidelity of the output would be my paramount objective.

Plain HTML is actually pretty awesome. It allows you to encode the structure of the document and then style if however you wanted. When I started in this business, you had to use LaTeX for that kind of flexibility. HTML has gotten a bad rep, I think, because it's dark side of including Javascript and a ton of frameworks for whatever perceived goal looks easy and seductive and then forces you into serfdom by obstructing future reuse.

If you stick with the bare minimum HTML you'll be fine. Better than fine actually. Text processors can these days usually import bare metal HTML just fine if need be. They only fail if you give them the "processed food" output of some kind of rendering pipeline.

The only other system for documentation we haven't covered in this thread is troff for man pages :-) Any takers?

The way of the world is this: ISO comes up with SGML, everyone gets a pat on the back, and then some guy called Tim who isn't even on a standards committee comes up with some bastardised version where you have to use angle brackets rather than generic customisable delimiter classes, and there's things like `<b>` for bold that are not even semantic. Guess which one took over the world?

I write a lot of markdown at work, and while you can't do this in commonmark, most parsers will absolutely let you define custom block types and transform the doctree and other things. You know how three backticks followed by the word 'python' produces syntax-highlighted code almost everywhere? You bet that I can do `::: warning` in my documentation to make the following content appear in a big red box with an exclamation mark.

As long as you don't put raw HTML in your source, you can even render to different targets like PDF. jupyter-book is a good example here.

I have grappled with the same conundrum. Here are my takes on documentation writing. First is the X axis of type of document we are called on to write. 1. There is personal writing. books included. 2. Personal Blogging and Dev Rel publishing. 3. Then there is developer tool documentation. [code snippets, sdks, libraries] 4. Then there is product documentation. [images, steps, how tos]

Then there is Y axis of tools. 1. markdown and with it Z axis of mkdocs, hugo, KMSs like obsidian <name everything markdown here> 2. rst 3. org? 3. wysiswg editors or anything custom.

I find - markdown both ubiquitous and somewhat approachable. for most beginners. with obsidian/logseq/... it can also work for non tech writers too. its also more widely supported. [Github i am looking at you] - dev rel/dev tools docs with sphinx and rst is absolutely godsend! also a vibrant ecosystem. - product docs with mkdocs x markdown if its a consumer facing docs with lots of images and need for customizing. rst if its a developer product.

---

I write my blog in markdown, https://blog.shaishav.kr

My team maintained https://userdocs.rapyuta.io in markdown for the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-docs

- we also maintained https://sdk.rapyuta.io/ & https://cli.rapyuta.io/ both in semiautomated rst + github actions setup

Here is how you would do your image example in Scroll:

rst:

    .. image:: example.jpg
      :alt: alttext

scroll:

    image example.jpg
     caption alttext

"Directives" in rST are "Parsers" in Scroll. The item above would be parsed by the `imageParser`, which at ~50 lines of code (https://github.com/breck7/scroll/blob/b8fd72aa38742cc6cd575f...), is actually more code than the average parser.

To write your "exercise extension" in Scroll, you would just need to write a few lines of code definining an "exerciseParser". You could put that in the same file you use it in, or in a file named "exercise.parsers".

I think you should explore Scroll -- https://scroll.pub/ -- might do everything you need in a simpler way!

I love rst. I love sphinx. I've written a lot of things with it.

But, I use markdown. Markdown is technically inferior, but it's just simpler and that's really what makes all the difference. There's things I can do in rst that are more logical, more powerful - and yet - I still use markdown and pictures.

To me, it's the usual problem that I like to illustrate with a config file:

while True:

  1. You need a config. You make a text file and write values in it. It grows. Its unmanageable. It's terrible.

  2. You write some proto to store the config. Its complex. It can do everything. It's relatively good but the more you use it, the more little problems show up. It looks like regedit, a sql database, a tree of trees, etc. 

  3. You throw it all away and write something with trade offs, that is reasonably simple, solve 80-90% of use cases and is otherwise somewhat limited. Sometimes, it feels like you might as well just use a text file.

Everything you can do with rst can be done now with markdown. But easier and better. The toolchain is superb now. MyST extends Markdown for technical, scientific communication and publication - https://mystmd.org/ and use Jupyterbook, which builds upon spinhx.

I used to hate Markdown (am partial to AsciiDoc myself) but it has "won" and I've just accepted it & use it every day. Not the first time an inferior product did so, and won't be the last. There are a few hills I'd die on, but Markdown alternatives are not one of them.

I am kind of syntax agnostic and would be happy to use more complicated syntax in exchange for more power. (I have a lot of HTML inside my Markdown files, too.) However, my use of rST has been in Sphinx, and I want to love it because it's quite powerful, but it's so slow. Am I missing some configuration or third party package to fix this? I wrote about 15k words of English text in rST in Sphinx to document a project[^1], and Sphinx's build speed was many times more an impediment than my unfamiliarity with rST.

[1]: https://pages.micahrl.com/progfiguration/

Ignores newlines (turns single newlines into spaces) so just as annoying as markdown for me. I'm looking for a text format that has some formatting ability, but preserves newlines you enter. BBCode is a good one.

What makes so many designers of these plain text formatting languages choose to not preserve newlines? I don't get it. Preserving newlines is one of the main features of plain text.

This causes the same annoying thing as hacker news comments do, like this intended multiline shopping list:

-eggs -flour -milk -sugar -salt

I used rST and Sphinx along with a custom built test reporter to generate a huge amount of test documentation for compliance. It really was nice to work with, especially since it is the default for python docstrings too.

I believe the big selling point is supposed to be the directives syntax of rST. I had a similar need to extend markdown, but pandoc already supports directive syntax -- and so do some libraries, eg., the marked library, which I use to render MD as HTML in-browser rather than with pandoc.

The iirc, syntax is :inline{property} and

    ::: block-directive {options}
        contents
    :::

It doesnt nest well, so I applied any document-level styles using the filename; but I'd imagine the yaml-style lead-in tags should be the correct way to do it.

If the author is here: Before the first code display, where you write:

    > Here's how to make an image in html:

I think you meant "markdown" instead of "html".

> .. image:: defines the image "directive". When Sphinx reads it, it looks up the registered handler for the directive

And the author continues to explain how rST is convenient and flexible to a doc engine like Sphinx. This kind of argument confuses me as a user. That is, why would I care? I just want to write my doc fast with minimal effort, and couldn't give zero attention to how Sphinx works. Wouldn't an average user like me should just ask: what will rST offer that is 10X better than Markdown?

"markdown is a lightweight representation of html"

No, markdown is a set of standards around transforming a good looking text file into a rich format(this is usually html, but it does not have to be). The most important part about markdown is that it is a "good looking text file". If a markdown extension does not result in good looking text it has failed the one point of markdown. This is why markdown editors leave me confused, the whole point of markdown is to write a nice looking plain text document, if you are going to use a specialized editor why not use a better format?

Note that markdown is a terrible document format, with only vague presentational cues and no semantic ones. it starts to suck real quick. However, it is a great idea if you want a good looking plaintext document. People understandably keep trying to "fix" markdown with better semantic options but these by and large miss the point of markdown leaving a ugly document.

So RST may be the best thing since sliced bread, but it is not really in the same category as markdown, the plaintext for one is decidedly ugly.

The problem with RST is the same with everything else: it isn't supported everywhere. I wrote a bunch of nice RST documentation at work, the next month some company wide team announced a new standard for documentation (backstage) which is markdown based, and has all the problems of markdown. (In their defense I'm not aware of any tool that would compete with backstage for what we need in a company wide documentation system)

A Table of Contents instruction that works across all markdown implementations would be an accomplishment.

OTOH, Markdown does not require newlines between list elements; which is more compact but limits the HTML that can be produced from the syntax.

MyST Markdown adds Sphinx roles and directives to Markdown.

nbsphinx adds docutils (RST) support back to Jupyter Notebooks. (IPython notebook originally supported RST and Markdown.)

Lemons vs limes. They're both markup languages, but they have different purposes.

Yeah, using markdown to write a book is very limiting and doesn't offer the control needed for typesetting.

OTOH, using markdown to write is liberating - you only get a few markup options, so you can focus on the content:

    [It is] notable that the Feynman lectures (3 volumes) write about all of
    physics in 1800 pages, using only 2 levels of hierarchical headings: 
    chapters and A-level heads in the text. It also uses the methodology of 
    sentences which then cumulate sequentially into paragraphs, rather than the
    grunts of bullet points. Undergraduate Caltech physics is very complicated 
    material, but it didn’t require an elaborate hierarchy to organize.
    
    Edward Tufte, forum post, ‘Book design: advice and examples’ thread

It seems like Markdown works pretty well for writing API docs, where the language has a tool for generating documentation that also gets things like type signatures from the source code itself.

The result of running that tool is always API documentation, so you might need something for docs that aren’t structured that way.

I dislike rST for how cumbersome it is with some of its markers. Trailing underscores, tons of dots, non-fenced sections, nested lists needing extra lines, etc.. It seems actively made to make it hard for me to read the source.

Now, granted, I am clearly ok with fenced sections. And I love org-mode for most all things.

To me the main deal breaker with reST is titles that must be underlined with punctuation characters at least as long as the title.

That's very annoying to write, and some people even add overlining. We're entering the ascii art domain here and I don't have time for that.

IMHO, ignoring the parsing difficulty, the main issue with Markdown is it's difficult to write for non-technical users- 1 misplaced character can mess you up if you stick to the "spec".

Markdown has already won over the technical users.

Enjoy your infinite support tickets caused by markdown. RST does nothing to help this.

rST is also much more powerful than Markdown. You can write an academic papar properly in rST. You can add custom directives implemented in Python and stuff. If I could make everyone use rST instead of Markdown, I would.

Of course Markdown is simpler in many aspects. But therefore it lacks many things that rST has.

I started looking at converting my books to use Sphinx (from pandoc) and got almost there. What stopped me was something a little odd: I wanted to use different fonts in a link, notably some proportional and some monospace in the same link. And it was my read that this wasn't possible...?

I’m not convinced. Markdown is cleaner imo and basically the standard. I see no reason to move.

I do appreciate that reStructuredText is extensible and Markdown (currently) isn't. I don't think that's an argument that outweighs rST's verbosity. But I do think it's an excellent argument for adding a standard extension point to Markdown.

This is why MDX rocks. It doesn’t have all of this builtin, but you get a lot of the same benefits.

I would say which is better depends on the use case. For note taking and most simple documents, Markdown wins hands down due to its readability and speed. For complex document sets where custom rendering may be required, rST+Sphinx is probably what you want.

Can't we all agree that both suck and everyone should use org?

Jokes aside, org seems to have a more clear specification and is very easy so use. Why don't more people use it?

I think Github already renders README.org as good as README.md and READEM.rst.

> You just need a regex to transform it into <img alt="alttext" src="example.jpg"/>.

Is this what the author means by markdown being lightweight, since the inverse isn't true except trivially?

asciidoc anyone?

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

Markdown might not be the best at anything, but it's pretty good for a lot of use cases and is beautifully simple. I can teach a non-technical friend markdown in about five minutes.

I prefer just vanilla HTML. It's easy to read and you can tack a stylesheet at the top to make it look actually nice and directly renderable in a browser without needing any parser.

> I can't get into lisps for the same reason.

I assume they’re talking about s-expressions? Then that’s a really bad example, because those are objectively beautiful.

Perhaps it is just how it was implemented the last time I used it but rST+Sphinx was so finicky and annoying that engineers just stopped updating the docs.

Sure, for quick throwaway notes or messaging apps Markdown is fine. But if I'm gonna sit down and write a proper document? I prefer handcrafting HTML.

I am proud to say this is might be the first time I finally agree with Hillel Wayne and something (at least mildly) controversial.

I prefer What You See Is What You Get (WYSIWYG.)

So it's more complex than markdown while being less powerfull than latex or org-mode? What a waste

rST is very powerful but if you have rST-illterate people on your team and you would like them to contribute, tough luck.

Passion for most powerful tech can take you far, but not tohers in your team. For others, Markdown has a much lower barrier to entry and is easier to preview in your local editor

Typst has a cool syntax and is highly extensible.

I wish there was a way to use it to render HTML and not just PDF.

I solve this for my usecases with custom Markdown rendering which accepts a few new block elements (via a markdown-it plugin). https://github.com/osmarks/website/blob/master/src/index.js

> ...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason.

I guess this is why he's not using Pollen, which is explicitly designed for this sort of thing, but based on Racket.

I actually settled on rST for writing fiction manuscripts, I think because I actually liked the syntax? Maybe I just needed proper header support. I'm compiling to DOCX via pandoc, so I'm not using the extensibility in the slightest. Anyway, it's amusingly validating to see someone else use it for a similar job.

If you want all that extensibility, use TeX or something similar. Or write HTML yourself. Markdown was supposed to be simple. Yes, you can't do everything you can do in HTML. That's the point.

I never gave rST an in-depth look. This article made me.

I am utterly disappointed.

I want markdown for writing loose text in a way that will be shared with and edited by non-technical people. If something is not formatted such that it can be placed in-line, then we're entering the real of "function" abstractions, which non-technical people DESPISE WITH A PASSION. They won't say it, but I'm old, and wise enough to know it's a mistake.

In other words, Markdown is just an expanded BB Code for me. And it does its job very well, because BB Code was insufficient.

So that's the context in which I'm disappointed with rST here. Because it look like... A poor man's LaTeX. This stuff is way too complicated for Markdown's use case, and way less complex than the demands of a book. I don't want to take the use case of LaTeX and use a worse tool. Disappointment. That's all.

For the motivating use cases, I wonder if YAML and a simple script to transform to other formats as needed would be more effective, easier to read, easier to write, and easier to work with in general.

No offense, but when I downloaded a sample PDF I expected to see a better formatting. The file is little bit clunky. I think it's not a failure of a formatter, but the design in general. The default markdown formatter in Leanpub works good enough, to a degree when I don't need to think about it.

So, while I understand all the good parts, I am still kinda not convinced it's a better option looking at the final product.

IMO the most important feature of markdown is that any random person, whether they are technical or not or know what markdown is or not, can view markdown-formatted text and understand it perfectly fine. A UI layer added on top is nice to have, but not at all necessary. Most alternative formats miss that critical point.

Ok well, that was insane.

I absolutely despise working with restructured text. Markdown I use allllll day long and it’s simple, fast, and a pleasure comparatively.

People like this just want to make the rest of us miserable.

My grandmother can create better docs than most programmers, but not because she's some technical wizard. She uses MS Word. Imagine, a program designed to allow humans to lay out and format a document quickly and easily... programmers prefer to hack up ascii art and forego the graphical layout and formatting tools developed 30 years ago. And then they complain that docs are hard to read/write...

"Now here's how to make an image in rst:"

    .. image:: example.jpg
      :alt: alttext

Great, I can close this article now.

> markdown is a lightweight representation of html

Never before on an article I've felt the vibes of the "I stopped reading there"-meme harder than here.

When you call a book v0.2 and say "now with epub, get it here" in the first line of your blog on why not to use the most popular of a thing, I am assuming we are going to be having a above board conversation about pros and cons, and I an receptive to your position.

When the first link is also the second link, and both are to BUY a 15 dollar book with the default "pay anything price" bar set to 20, I am just clicking out and ignoring literally everything in your marketing post.

Others can discuss this RST thing I have never heard about, I am just here to point out you have now alienated one of your potential converts. Put the book link at the bottom, and dont double link to the same purchase page in the same paragraph. FFS.

RST might be technologically superior but markdown is easy to write and has a huge ecosystem.

For hobby usage, use whatever. But I would strongly oppose anyone who would try to make RST standard at my workplace.

A scrum-master, PO or marketing can write markdown. RST would be a hard sell.

>The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree.

Not really. Quoting https://en.wikipedia.org/wiki/Markdown

>Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions, unlike text formatted with 'heavier' markup languages, such as RTF, HTML, or even wikitext

So, for use cases that don’t make a good match of this chief constraint, Markdown might not be the most relevant option. It’s just as meaningful as saying that we prefer TeX over Markdown because fine typographical tuning is an important concern of our specific usecase.

I admit I already dealt with a screw using a hammer, not having the right toolset at hand. But when the situation don’t call for adhoc heterodox actions, I prefer to match a screwdriver with a screw and a hammer with a nail.