I prefer rST to Markdown | Hacker News Reader

I prefer rST to Markdown

buttondown.email

355 pointsBerislavLopac422 comments

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

I thought Markdown was clearly very silly back when it started gaining traction amongst developer types. There were already so many other better options--even at the time--for plaintext-to-formatted document markup languages.) But still, developers were designing whole apps (CMSes, productivity apps, document management, etc) and plugins around Markdown, sometimes as businesses.

But then I realized, after using it in some apps, that wasn't really what Markdown was about. Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. The amount of formatting it supports is small _on purpose_, so that it fits in your brain and doesn't require a toolbar to use. It is _meant_ for things like comment fields, chat programs, commit messages, and so on. Maybe even blog articles. But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

These days, I write Markdown even in place where it will never be rendered into HTML. Because it's quite readable as-is. (And I wish HN supported it.)

Markdown is like a virus of an idea:

1. Apparently simple enough to implement to get the basics right (not that I could do it)

2. But there is plenty of room for accidental edge cases in the implementation

3. Many then implement it with or without edge cases

4. But it’s not enough because a lot of the people who use it are programmers so they naturally want to extend it to do just a little more

5. Now the standardization effort (Commonmark) has to take all of those edge cases into account plus have to figure out how to deal with extensions (especially for popular ones)

6. Then you get a heroically (in terms of effort and grit) wordy standard

All for the initial idea which is so simple that it seems redundant: look as good plain as rendered. (Then what’s the point of rendering it, and in turn what’s the point of a formal syntax instead of the (still existing) ad hoc email and whatnot conventions?)

Right now it’s fantastic for chat applications (here you definitely want rendering and not the visible markup). It’s been pretty good for things like forum comments as well. With the exception of block quotes which are a pain to fiddle with (the only prefix syntax if you don’t include the indentation-for-code since that is de facto optional now that so many applications support code fences… all because that’s how email does it).

To be fair, John Gruber offered up a completely deficient “standard” and a buggy as hell Perl parser implementation. Yet still wears “I created markdown” as a feather in his cap, strongly insists to this day that it was a good idea, and says “the canonical markdown docs are on my blog! Nothing else is markdown!” Things like CommonMark were absolutely integral to Markdown’s current success. It was way more about fixing John’s mistakes than adding more functionality.

> 3. Many then implement it with or without edge cases

> it’s fantastic for chat applications

Slack is the absolute worst at it; I am unable to at all figure out what its "parser" (which feels like cobbled together regexes … but even then … not?) is doing.

  [link text](URL)

is sometimes a link. But sometimes not! Sometimes Slack mutates your message, and then renders the mutated version — and this is visible if you subsequently edit your message, as what is now there != what you type. When it works it is nice, but when Slack decides it doesn't like that message, in particular, it can just be a pain to get it to do what you've typed.

Worse to me is that Slack considers "we mutated the input you typed, and then proceeded to misrender it" as "Won't Fix/Working As Intended". (I reported it a while ago, that was the resolution.)

> All for the initial idea which is so simple that it seems redundant: look as good plain as rendered. (Then what’s the point of rendering it, and in turn what’s the point of a formal syntax instead of the (still existing) ad hoc email and whatnot conventions?)

It's intended to look as good as possible in both mediums. It is not possible for the raw text to look as good as the rendered text and still be easily writeable, because the raw text cannot generate visual hierarchy using font size and weight.

I suspect you know this, but when you say readable raw text seems like a redundant idea, I'm not sure what point you're trying to make.

Markdown is the Unix of rich text formats.

The hours I spent chasing down the edge cases with inline html! There’s some real nuance to the spec there.

You need inline html fairly often for anything non-trivial, and some of the rules certainly aren’t intuitive or easy to remember.

That said, like JSON, it won by being both simple to grok and good enough for most use cases.

I arrived at a similar conclusion, just from the other direction: It is really hard to get people to document. It is even harder to get those people to care a little bit about formatting.

Markdown is... limited, I acknowledge. But with a very small amount of learning, markdown is as fluent and simple to write as normal text. In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.

If you asked people who don't document to document in rST or tex... then you'd have no documentation at all. Because that suddenly adds a lot of effort on top of what you want to write down.

Now for some customer-facing whitepapers and documentation, we do use rST. But there you have people who are tasked with paying some effort to create some decently looking docs. Not trying to coax developers into writing down some of their state of mind while doing stuff.

Although, I have to say, it is a sad state of afairs, if rST is already too difficult for a person with the job role "programmer" to use. If this is already the threshold, which would stop them from writing documentation, then I have my doubts about the quality of documentation, that they will write in Markdown.

Small barriers matter. Anything that kicks you out of the flow makes a huge difference. And rST is confusing enough often enough to kick you out of the flow.

Agreed. Mandate function docstrings? You'll get "Function FlargleBlab blabs the flargle" docstrings. Just useless.

Ironically, that was my argument for getting rid of Confluence. Confluence should be the low barrier to entry solution, but its buggy, clunky GUI ends up actively punishing anyone who dares try to update docs. So a repo full of markdown files with a self-merge pipeline ends up being lower-resistance.

I wonder if Spotify was right on the money with their Techdocs approach. It's all just Markdown files being rendered in another format, and the edit button is just sends you to a github or equivalent editing page. People want the idea of a platform... but do they need one?

Yes!

Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.

> In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.

Bingo!

>Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML.

My gripe is that it really isn't. Because markdown inevitable includes images or something and the instant it does it doesn't hold up to it's killer feature. Now you can't read it properly, so now you have to find a generated version, or hunt down the images manually, or generate the output yourself.

Alternatively, the document is so trivial that even markdown formatting is too much (just distracts) and doesn't add anything of value.

It isn't that bad, it just never seems to make any sense for files. It does make sense for web forms though but that's only because you never read the markdown, you just write it and the output is generated on the fly.

When you use one of the extensions, like Hugo's figure, which has alt-text support you're about as close to that goal as possible. An image can't be stored in human readable plain text.

The alternative is WYSIWYG formats that aren't plain text.

Doesn't matter how close to the goal you get if it is on the outside...

I'm gonna be annoyed if I clone your repo, open the readme.md and now have to figure out how to read it.

Plain text is awesome, for plain text. If it isn't plain text might as well use a pdf.

> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables.

Most enterprise web applications would probably be completely fine with just markdown-based docs.

I think a good example is all of the wonderful documentation that's been created with mdBook.

Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that.

https://github.com/rust-lang/mdBook

Carol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print.

That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.

The link below (https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?

> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

MDN documentation is written in markdown. I’ve always felt this was a resounding endorsement of markdown over other more “powerful” markup languages because if they can do it, why can’t you? (not you in particular, but anyone who thinks markdown is inadequate for docs)

https://developer.mozilla.org/en-US/docs/MDN/Writing_guideli...

All my documentation at work is written in a dialect of markdown. It's absolutely the thing you want, together with a good parser and content management system for producing a site with search, navigation etc.

As we’ve gone horizontal on tool chains instead of vertical like we used to, what you want is a bunch of mentally cheap tools with high bang for the buck. Get in, get out, move on to the next of fifty tools you have to deal with each week.

Well said. But, uh, there’s no “maybe” about Markdown being intended for writing a blog. That’s literally exactly what I made it for — for me to write Daring Fireball.

Yeah, I still have thousands of Textile pages, but all of my newer stuff is in Markdown…

I have used markdown to write books, and it worked just fine. Now, these were novels, not technical documents, but I never encountered something that couldn't be solved with markdown plus some occasional HTML.

I've also generated quite a bit of technical documentation using markdown, and Pandoc's extensions[1] allow you to include pretty much any formatting you might require, complicated math and syntax highlighted code blocks included.

That markdown can then be transformed into HTML, a Word doc, a ePub, a PDF ...

There needs to be a very compelling reason for me to reach for something other than markdown.

[1] https://pandoc.org/MANUAL.html

Here are some Markdown books I've crafted:

* https://whitemagicsoftware.com/softcover/technical.pdf

* https://impacts.to/downloads/lowres/impacts.pdf

* https://whitemagicsoftware.com/softcover/jekyll-hyde.pdf

My blog describes shell scripts to use pandoc and knitr for converting Markdown to PDF:

https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...

I wrote a FOSS GUI/CLI cross-platform desktop application to replace those shell scripts:

* https://keenwrite.com

* https://keenwrite.com/screenshots.html

* https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9...

I'm using KeenWrite to write a sci-fi novel and can produce a standard manuscript format in seconds (because the content is kept separate from the presentation).

Regarding technical documentation, I extended Markdown in KeenWrite with a consistent cross-reference syntax for tables, figures, equations, etc.

* https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/ref...

about keenwrite, touting "producing beautifully typeset PDF files" and not giving a single PDF example, ideally its documentation, is a missed opportunity, to say the least ;-)

Most novels don't need anything more complex than a link to the next chapter at the end of the page. Maybe bold text, but a lot get by without. As such markdown will work for most. I've seen some novels with some really complex formatting, but those are rare (I read a lot of litRPG and still call them rare). However I mostly write technical documentation and I often hit limits of things markdown cannot do even though my documents are much shorter than a novel.

Pandoc is a great thing! However, lets not mix up Pandoc Markdown with standard Markdown. Pandoc Markdown intentionally adds features, that make it more suitable for academic writing, I believe.

I am probably in the 90th percentile of TeX users, but I have to say that it's hard for me to think that there's much space between markdown and TeX for another typesetting language. Markdown is easy to write and read but very constrained, while TeX is a bit harder and essentially infinitely flexible.

The biggest issue I have seen with TeX is a people problem: people frequently write spaghetti TeX with horrible style. This is terrible, but it is not actually a language issue. Writing it with a "docs are code" mindset can produce some very clean results. The second biggest issue is that there isn't a good TeX -> HTML compiler.

"The second biggest issue is that there isn't a good TeX -> HTML compiler." This is the crux of the problem in using just TeX for writing books: it focuses on producing camera-ready output at the expense of literally everything else.

reStructuredText isn't itself a typesetting language. It's meant to be something of an interposer between the semantic meaning of what you're writing and the thing that does the typesetting. The hope is that it, unlike something heavily constrained like Markdown, gives you the tools to capture that semantic meaning and transform it into something that can be typeset.

Like, the goal isn't to throw out TeX. The goal is to be able to target TeX as a typesetter along with Web browsers and e-book readers and even things like GNU info and troff without having to rewrite the content wholesale to fit each one.

Personally, I would rather just have TeX itself target the web rather than wedging another layer into the typesetting stack. As far as I know, other than the sheer size of the language, there is nothing fundamental stopping someone (I guess me, eventually) from writing "htmlatex."

Modern web pages are already designed with "camera ready" in mind, essentially with browser width being the only thing that changes layout.

Maybe Typst (https://typst.app/) is a good in-between?

I used typst for a recent project and I love it. It’s essentially all the power of latex but with modern sensibilities. And it’s a cute little programming language - with support for variables, functions, json data loading, 3rd party libraries, and all sorts of other nice to haves.

I just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.

Indeed, I don't see the reason for someone to learn LaTex now that Typst is here.

You should check out Scribble which uses Racket. It has a bunch of different renderers including HTML and Markdown. However, unlike Markdown, you can easily write extensions for it in Lisp, even within the document itself. https://docs.racket-lang.org/scribble/running.html#%28part._...

I suppose that makes it inappropriate for something like rendering comments, but it's a great way to write documents. I used it a lot for writing papers since there's a lot less boilerplate and was much easier to use than TeX.

My problem with the TeX ecosystem is it's so non-modular. Bring in this package to add a new font with some extra dingbats, and suddenly you lose proper linebreaking inside boxed environments. And so on.

What advice do you have for writing "docs are code" LaTeX?

I find LaTeX to be the lesser of evils when creating PDFs. However, I rarely deal with LaTeX issues these days because all of the pain points have been patched away in my tooling that converts md to tex. However, I keep thinking something more modern or faster (like Typst) might make my life as an author easier. Compiling LaTeX with tools like rubber is still painful and slow.

A few things:

1. Separate each part of a document into different TeX files and include them in the main document. Each file should be a separate unit of the work. Only compile the main document when you need to.

2. Generally write with readability in mind and use newlines and other whitespace in the source a lot more than you think you should.

3. If you have common boilerplate that you frequently use at the top of docs, make your own package(s) for those commands and maintain that separately.

4. Refs and labels everywhere you possibly can. Also, prefixing your label names helps a lot, so \label{clouds} on a picture of clouds becomes \label{fig:clouds}. If you are writing a book, and this is the chapter on the sky, consider \label{fig:sky:clouds}.

TeX is old and busted; Typst is the new hotness. Written in Rust, too!

"Written in Rust" matters to very few customers of your office webapp. And you should add that it is $8/month for an online platform, not free or self-hosted.

> I don't want to write a book. If I did I'd use LaTeX before RST.

To me this seems a horrible decision at the stage of writing/structuring. I'd rather write in Markdown (this way I could just write, without bothering about typesetting) and only convert to LaTeX for publishing. I'm not proficient in LaTeX though - I once tried to learn it and it felt like learning a language of an insectoid extraterrestrial civilization - completely unintuitive, almost impossible to do anything new - what hasn't been already done by someone else enabling you just copy-paste your own text. IIRC it doesn't even have first-class Unicode support.

In LaTeX you also clearly separate structure and typesetting: you don't write \noindent\textbf{Introduction}\nobreak\medskip or whatever, but simply \section{Introduction}

Macros are also pretty easy to define \newcommand\important[1]{\textcolor{red}{#1}}

And of course it has first-class Unicode support

Easy is relative. Latex is sooo much uglier than typst:

    #let important(body) = {
      text(red, body)
    }

    But whatever you do, #important[Dont *panic*!]

Docs:

https://typst.app/docs/reference/foundations/function/

"In LaTeX you also clearly separate structure and typesetting ..." Not quite.

The rub comes in when you want to pull that content out to render it in a format that isn't meant to be camera-ready, like a Web page or an e-book. TeX, even with Leslie Lamport's LaTeX macros, doesn't give you an ergonomic mechanism for marshalling out the semantic structure of your document to reuse elsewhere.

You're left parsing the TeX yourself, and that sucks.

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

That's not true, even at the basics it's not great, let alone the best: asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/

And then outside the basics it's not that easy to write/read either, you'll get lost in bad formatting of tables or metadata (tags) obscuring text or what not without proper tooling

> How easy it is to extend is largely irrelevant

It is relevant as then you could fix those basics if you could easily and conveniently extend it

> asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/

This has always baffled me. _underline_, /italics/, bold.

And then you have programmers talking about _private_method and /some/path/

Then put code things in `grave_marks`, etc.

not a good argument given the fact that underscore _is_ already a bold markdown syntax

And it actually can be easily extended with custom blocks ( ::: ). https://github.com/vokimon/markdown-customblocks

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

I'd go so far as to flip those two. By far, it's more important to ensure that documentation can be easily written (the raisin d'etre of MD) than it is to optimize for the job of the people trying to collate/edit/format/improve/maintain the documentation (something that RST speaks to, primarily).

Because the primarily failure mode in this space is not that we have imperfectly edited documentation. It's that we lack docs at all, because the hackers didn't understand the doc tools.

In Zephyr, we use RST. And... it's fine. I've made my peace with it. But "please write some docs" is a routine comment in review, and in my experience many-probably-most contributors just don't know how and don't want to take the time to learn. The barrier to markdown would be much, much lower.

Yes, that is a good rephrasing of the rest of the paragraph you quoted.

> Because the biggest advantage of Markdown is that it's easy to read

Do you really read Markdown in plain text editors? I only do occasionally (nevertheless I'm glad I can). Most of the times I use tools like Obsidian, Typora, Markdown Monster etc.

HTML is just too bad for plain source reading relatively to Markdown and too complex for reliable mapping between what it is looks, what it means and what it is.

This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have.

There certainly are cases where Makrdown seems the best choice - wherever simple plaintext editors are going to be used often. Nevertheless I doubt Markdown is the best choice for tools like Obsidian - perhaps people working on new projects of this kind should also take a look at rST or AsciiDoc.

I'm with you on that, I can think of one counter example though, and that is when you have to write your MD in something like VS Code. Which uses the old-fashioned approach of source code pane and render pane. I strongly dislike that and usually try to get away with source-code view only. To be fair, they use a tiny bit of coloring, so it's not 100% plain text. And the better solution is to write your MD in any other MD editor except VSC, of course.

When you're putting documentation in the same commit as the relevant code - which is good practice, at least around here - then it's often useful to be able to read not just markdown but a diff of markdown as plain text in ${editor}.

> This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have.

Revive Textile? It was one of the inspirations for MD, IIRC.

> I don't want to write a book. If I did I'd use LaTeX before RST.

100 times yes. Markdown for light styling. LaTeX for anything else. The next revolution in standardized text parsers will not come from replacing Markdown, but from replacing LaTeX.

Every heard about https://typst.app/?

I don’t think the global standard of scientific paper writing will be replaced by something that has a pricing tab at the top of the page.

https://github.com/typst/typst

yup - my knee jerk reaction at seeing the first couple of samples was to recoil. Great if it works for ppl but I'm gonna stick with markdown.

If it was only about this, personally I find org-mode is better than markdown.

There is a big gap between a book and informal notes, docs, comments though. At least big enough to drive several tools into, or they wouldn’t exist.

What are some non-emacs tools (more advanced than notepad.exe or TextEdit.app) for editing org-mode?

Markdown has 30 different flavors because it grew organically and has no formal extension mechanism. "What am I allowed to use in this markdown processor?" never becomes an issue with reST.

Markdown has 30 flavors because it has over 30 different ecosystems using it. We have github flavored markdown, gitlab flavored markdown, MDN markdown etc. because github, gitlab and MDN are all using it. If you forced everyone to move to rst, then you'd see flavors cropping up soon too.

Even if rst has a generic extension mechanism, on github you'll spend a lot of time referencing commits, tags, users, pull requests and that kind of thing. So you end up having to know a domain-specific language anyway, whether it's formally presented as an extension mechanism to the language or as a dialect.

> I don't want to write a book. If I did I'd use LaTeX before RST.

You'd want to use Typst, not LaTeX. I'm rewriting my CV with it, it's fantastic. I can now finally put the CV contents in a JSON, and generate the PDF programmatically, with lots of computed values by my own algorithms, the layout is simple, nothing stands in the way, nothing feels out of its place. And compilation is so fast... Really, forget LaTeX, embrace the 2020s.

That was a rhetorical question in the article. It's immediately followed by:

> ..Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.

Uhm, reST is also easy to read and write, at least where Markdown is easy to read and write.

To me, they are largely the same thing, with slight syntax differences, with reST being more readable as it's clearer what any special syntax is about, whereas MD is more concise to type out — you need to learn the special syntax whatever way you slice it.

FWIW, reST was the default for Python "doctests": a wonderful feature that has fallen out of favour for some reason, but has the potential to be your real runnable documentation.

I wouldn't write a book in either, but that's because I am really high on great typesetting — I even had my own set of (Plain) TeX macros to do ToC generation, syntax highlighting, alternative math fonts, support for UTF-8 before eTeX and such when I did write papers and handed in coursework regularly.

> reST is also easy to read and write, at least where Markdown is easy to read and write.

It isn't though. It's just a whole lot more annoying. On paper the syntax differences are small, but they make the writing experience so much worse. I wanted to like rST but it just isn't good enough in use.

If rST were actually easy to write and read I would have just used rST instead of creating Markdown.

Except for native Python tools like Jupyter, which have all moved on to md.

(I still like doctests and use them extensively in my books.)

I couldn’t say it better myself. Thanks.

The very next paragraph in TFA agrees with you:

>...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.

What do you use for the actual, non-quick documentation?

Markdown is pretty bad for note taking, it has a niche functionality suited for basic text based note taking. Unfortunately that isn’t the only note taking that is possible

This is pretty much the paragraph that follows the paragraph you cited...

If you'd read past that, the author says "yes, those are good reasons, I would too".

rST and md are both not ideal for writing books. And LaTeX is even more painful. IMO using md is the lesser of two evils. I'm done kicking against the pricks with rST.

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.

> 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

This, so much this.

It's a problem in an even more general form (for you're writing about linking to sections within a page): the number of CMS systems or static site builders that make you insert the final URL when you write is _insane_.

If the slug changes, you reorganise your site - now you have to do a search and replace through the site to update all your links.

Static site generators could enable linking like [Hello](../hello.md) and resolve the link at build time, instead of expecting everyone to type [Hello](/why/hello/). And yet the popular ones I've used or looked at don't do this.

It seems to be a marmite feature (you love it or you don't): I've raised it with static site builder team members and received a "Why would you want that?" response. Explanations got nowhere. I'm not sure if it's a niche feature, you have to have experienced the problem to appreciate the solution, or people are used to writing once and not maintaining for a decade or longer, but it'd be great to see wider support.

Agreed that Sphinx is extraordinary and wildly underrated. Sphinx is the only architecturally sound, extensible, widely used documentation framework that I know of. Its plugin ecosystem is amazing and gives me incredible leverage to improve documentation for teams and projects.

I'm not a fan of reStructuredText, but nowadays it's possible to do most things that previously tightly coupled Sphinx to RST in Markdown, courtesy of MyST-Parser: https://github.com/executablebooks/MyST-Parser

Except that the plugins are not compatible with each other or the latest version. That means I'm seeing some bugs that are fixed in the latest but I can't get the fix because my doxygen plugin doesn't work with the latest, and even if it did is the mermaid plugin updated yet? (please don't ask which versions of each I'm using - I believe there are at least 2 different ones that can do both of the above and they all have different abilities...)

Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed).

I found this to be very easy using Markdown+pandoc. I turned image tags containing youtube links to thumbnails with video tag and alt text, hooked up image tags to local video files to ffmpeg to optimize and resize videos to then do the same, etc in a few lines of code.

I did not know about Sphinx until your comment (I'll get to my 2-day delay in response, briefly). I've been doing technical writing "on the side" as my dev work allows, for 20+ years. I've been a TeX/custom-XSL sort of dude the whole time.

I just ported a 200+ page book documenting an internal language/VM/abstraction-layer to Sphinx ... holy moly, this is a life changing system!

I wish the documentation for Sphinx, itself, had a lower ramp and/or more examples; otherwise, I'm still in a pretty fantastic honeymoon phase.

My two main lines of research are how to build good looking PDF (books); and, some sort of system to let me cut a book into POSIX compliant man pages by chapter/section.

If you want Sphinx to achieve that breakout success, priority #1 should be to get high-quality, beautiful themes.

At least for me, aesthetics are a high-priority factor when deciding which site generator to use. Hugo and Gatsby have great built-in themes, and I have chosen them for projects before based largely on this fact.

The Sphinx themes here [0] and here [1] are various levels of "meh" to bland.

Look at the standard Sphinx RTD theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/

Now, compare it to documentation sites like:

- Apple's: https://developer.apple.com/documentation/swift/array

- Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-developer-po...

RTD looks dated in comparison.

[0]: https://sphinx-themes.org/

[1]: https://sphinxthemes.com/#featured-themes

I don't disagree that themes are an important part of marketing a tool. The engineer in me doesn't want that to be the case, but I recognise that people like pretty things, it makes a difference.

However I'd push back a little. That Fluent UI doc site looks like every other doc site from an open source project started since ~2020 that I've seen, and this means that I have certain expectations: I expect the project to be immature, I expect the docs to be incomplete or out of date, I expect the search to be an annoying AI search that does a worse job than the basic full text search that I expect elsewhere, I expect that to get anything of substance done I'm going to have to hang out on a Discord server. When I see a ReadTheDocs site though with that default theme, I expect the project to be somewhat mature, I expect it to basically work. I expect the docs to be fairly complete.

Are these expectations fair? Not really, but that's the whole point here. Open Source projects are not immune from marketing, and when marketing, what other similar projects do will affect how people respond to your marketing. Nothing exists in isolation.

In my experience, engineers think marketing doesn't apply to them, but these impressions really do matter.

I agree that more stellar, super-visually-appealing themes will help Sphinx get to the next level.

One nit: I called Sphinx a sleeping giant because it's already majorly successful in the Python ecosystem. Pretty much all big Python docs sites are built on top of Sphinx, including docs.python.org. But I think it's fair to say that when Sphinx starts getting major adoption outside of the Python ecosystem then we can start calling it a breakout success.

Looking at Fluent UI VS featured-themes, I don't see a difference.

I'll ignore Apple because: 1) It loads _extremely_ slowly (10+ seconds). 2) Just looks like a dark theme and nothing more.

Apple's site loads for me in under 1 second with a clean cache force-reload.

The featured themes, in general, have poor typography and whitespace, poor formatting and alignment, and uninspired colors and design. Furo [0] is the best-designed of them and would make a solid foundation for a proper theme.

[0]: https://sphinxthemes.com/themes/furo

Some drive-by feedback on pigweed.dev: It seems like it’s missing a “What is Pigweed” section? I was wondering what Pigweed does and eventually found the Github README, which is somewhat better. (I’ve used Arduino, but I’m not quite sure what I’m looking at.)

Thanks. It's basically middleware for large, professional embedded development teams creating mass market products, usually consumer electronics. The four pillars in the "What is Pigweed?" section on the homepage [1] really do sum up a lot of what we do, but the reality is that it's a difficult "product" to explain in general. But rest assured that it's definitely on my radar that there is huge room for improvement in our "What is Pigweed?" content.

[1] https://pigweed.dev/#what-is-pigweed

Apparently I'm bad at skimming. I did see that section, though apparently not the heading :)

The first part didn't really do it for me because it seemed too meta:

"Over 150 libraries" - to do what? (Actually, some good examples are in the next section.) "Automation" - to build, test, and lint what? "Environments" - to make builds reproducible, to do what? "Frameworks" - turnkey solutions for what?

They are clickable, though, so maybe I should have clicked. :)

> We provide libraries (modules) for strings, time, assertions, logging, serial communication, remote procedure calls (RPC), and much more.

Maybe put that up front?

Looks like "frameworks" are still work in progress; maybe I'll check back someday when they get to Raspberry Pi Pico support.

I liked it as well. But many years ago I tried to get them to implement parts of a book, and they never did. You can work around somewhat by hardcoding chapter numbers—but I don’t feel sphinx is suitable for book-length docs without that simple feature.

Until you need to make a physical book with Sphinx or write custom tooling with it...

Why do you like Sphinx so much? Have you ever used MkDocs/Material for MkDocs? How do they compare?

At my last job I spent a fair amount of time on documentation, but I don't have a great understanding of what technical writers like/dislike, or what documentation systems are best.

I like sphinx because I can make it do all the weird links between documents that I want. Markdown can't do that. I've never used MkDocs so I cannot comment.

I've used both extensively. (Material for) MkDocs is easy to set up and gives very good UX for users. Sphinx is hard to set up and provides better UX in some ways (internal links are on another level entirely), and worse UX in others (the themes are all worse than Material for MkDocs, every single one).

Ok, what about DITA?

Also very powerful. Haven't worked with it in years; need to revisit.

> reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great.

So, you've made a convincing argument of why we should prefer Markdown to reST, 9 times out of 10. If we're working with Sphinx we'll give it serious consideration.

I heard recently that MyST [1] now has full feature parity with everything that reST provides. If I were starting a new project today I would seriously look into Markdown-based Sphinx site powered through MyST. For Pigweed we collectively don't seem to hate reST enough to justify the huge project of migrating everything over from reST to Markdown.

So yeah, I don't really have strong opinions on sticking with rest per so. I only have strong opinions about Sphinx being probably the best choice out there for large docs sites.

[1] https://myst-parser.readthedocs.io/en/latest/

I'm not really sure what your point is. What you're saying agrees with both the parent and the OP.

My point is that the reason GP prefers rST is a reason not to prefer it, usually.

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

The very first sentence in that link says “Markdown is a text-to-HTML conversion tool for web writers.”

Gruber did not take a "de facto standard" from Usenet and simply write an HTML converter for it. He designed his own markup, borrowing from Usenet and other conventions. The “Acknowledgements” section at the bottom of your link alludes to this fact.

Markdown was from the beginning intended as a markup syntax for web CMSs. To say it is a lightweight representation of HTML is correct. The whole point was that every part of the syntax produce a direct HTML equivalent.

Gruber writes that Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

> To say it is a lightweight representation of HTML is correct.

It's correct in the context of (2) but not (1). In the context of (1), Markdown is a lightweight markup language for rich text. For example, Pandoc can convert Markdown to formats like PDF, LaTeX, and ePub.

It's also true in the context of (1), since the syntax specification specifically falls back to HTML for difficult things like tables.

This is made abundantly clear on the Syntax page[0]:

> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

> Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

Markdown is very coupled to HTML, and is hobbled as a result compared to formats like Tiddlywiki and Org that not only have sophisticated syntax for all kinds of content like tables, but also directives to the parser itself to render particular blocks using an external tool. I wrote a bit about this in 2021 in response to query about why Org mode doesn't use Markdown[1].

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

[1]: https://rpdillon.net/why-doesnt-emacs-org-mode-just-use-mark...

Isn't inline HTML valid within Markdown? You could say that Markdown is a superset of HTML.

That's an excellent point. Time to update https://www.wikiwand.com/en/Markdown. :^)

It depends on the dialect you are using. Some support a limited subset of HTML, some allow all and some allow none (maybe HTML/XML comments).

> Markdown was from the beginning intended as a markup syntax for web CMSs.

As a matter of history you're right, just as JSON was intended as nothing more than the literal syntax for JavaScript programs. But it turned out to be a lot more widely applicable.

> To say it is a lightweight representation of HTML is correct.

No, it's a representation of writing. It represents the input not the output.

The comparison JSON is apt.

The first few years after I released Markdown, it was far less popular than I expected and hoped it would be. But it grew, and then for a years it was as popular as I’d expected. But then it kept growing, and now it’s far more popular and widely used than I’d ever thought possible. I genuinely now think it’s used in many cases where it shouldn’t be, and exposed to non-technical users who should be using something WYSIWYG, not markup.

I disagree. Markdown has always been about HTML - to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.

The fact that Markdown was inspired by email conventions doesn't make the statement "markdown is a lightweight representation of html" any less correct.

I thought a goal of Markdown was to be a set of conventions that were readable on their own as well as being transformable to a rich text/HTML representation.

You can read a Markdown document pretty easily using "less" or any other character-based interface.

The same is not really true of reST.

Maybe I'm confusing that with some other plain-text markup convention?

all of that is true, but markdown targets HTML as its "native backend", if you will. it is not feasible to render markdown -> pdf without having an intermediate HTML representation.

this is clear from the fact that HTML can be inlined in a markdown document; this is part of the spec (in so much as there even is a "spec" for markdown, anyway).

reST is also designed to have human readable source. You might not like it compared to markdown but it has to serve as a the docstring format of Python and does so fairly well.

The article convinced me that markdown is better for its purpose.

> to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup.

Some Markdown parsers support some HTML. You cannot, for example, add a YouTube video embed to a GitHub comment. Webpages that allow Markdown quite reasonably limit what’s accepted.

Usually, the colloquial conflation of Markdown with CommonMark and the numerous Markdown-esque dialects is helpful language, I've defended it here before.

On this question, it isn't.

Markdown qua Markdown, unambiguously supports HTML tags. You can verify that yourself: https://daringfireball.net/projects/markdown/

The introduction being:

> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

It's not possible to read the original specification without agreeing that, yes, Markdown is specifically a way to generate HTML. It also has a nice syntax which has become popular in contexts where embedding HTML isn't a good idea, and there are some tools which allow Markdown to be converted to other formats as well (usually, but not always, these disallow most HTML tags, meaning that they aren't Markdown sensu stricto either).

I would say that all of this supports Hillel's basic point here: Markdown is in fact tied to HTML semantics, in a way which makes it painful to do things with it which aren't tied to those semantics in the same way. Dialects in the Markdown family exist which make this less painful, and they do so by diverging from the original Markdown spec.

> Markdown qua Markdown, unambiguously supports HTML tags.

The section I quoted (and responded to) didn’t say “Markdown supports HTML tags”, it said (emphasis added) “Markdown parsers support (…)”.

So unless you’re arguing that a tool cannot be considered a true Markdown parser¹ unless it parses HTML, the distinction is irrelevant. I wasn’t making a general argument, I was responding to a specific claim.

> You can verify that yourself

Yes, I am quite familiar with that subpar piece of code and specification. I have spent some time implementing a Markdown parser myself (the output wasn’t HTML) and Gruber’s resources were by far the worst. For various reasons he has been an awful steward of Markdown; its ubiquity is despite him, not because of. Forgive me if I don’t find the author to be the authoritative source anymore.

¹ https://en.wikipedia.org/wiki/No_true_Scotsman

Gruber:

> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Both Gruber's original and CommonMark (the closest thing to a standard) support inline HTML.

Both Gruber and CommonMark specs are defined in terms of its HTML output.

Yes, that’s why I said “some”. I don’t understand what’s ambiguous about that.

Dear HN: stop leaving comments like this. It's arguing over semantics and makes for boring conversation. It also violates HN guidelines for leaving comments:

- Please respond to the strongest plausible interpretation of what someone says, not a weaker one that's easier to criticize. Assume good faith.

- Please don't pick the most provocative thing in an article or post to complain about in the thread. Find something interesting to respond to instead.

https://news.ycombinator.com/newsguidelines.html

If you disagree with the substance of the article, say you prefer Markdown to rST, then address that. Explain why despite the author's preference for rST, you prefer MD. It's silly to argue over this single sentence about exactly what Markdown is or isn't.

Markdown, Markdown, is nothing to do with email and Usenet formatting. It was a specific syntax, poorly defined, which has since become a broad family of mostly similar syntaxes; and it was inspired by various conventions from things like email and Usenet, some of which predate computers (e.g. pretty sure I’ve seen or heard of asterisks being used for italics in old typewritten stuff); but Markdown is all about HTML, its syntax is extremely constrained by HTML, and any attempts to separate it from HTML are fairly thoroughly doomed.

Saying that it has nothing to do with email/usenet is a bridge too far in the other direction, it was very much inspired by such formatting, something it never hid: https://daringfireball.net/projects/markdown/

> the single biggest source of inspiration for Markdown’s syntax is the format of plain text email

Yeah, it was inspired by those things, as I said, but it was never connected to them, and is quite incompatible with them.

I also express things that strongly because I’ve observed a distinct tendency to interpret Markdown as the successor of those things or the inventor of such syntax ideas. Whereas in fact, Markdown was not the first lightweight markup language, and is not the only one, and isn’t even the LML unquestionably closest to plaintext email conventions (reStructuredText is an obvious contender; overall, I’d consider reStructuredText a little closer than Markdown, but it’s subjective).

Perhaps my intent would be more clearly expressed by inverting it: email formatting has nothing to do with Markdown.

> Yeah, it was inspired by those things, as I said, but it was never connected to them

You seem to have a very peculiar interpretation of the word "connection"

> and is quite incompatible with them.

It can't be incompatible with ad-hoc unspecified and informal formatting habits.

> Perhaps my intent would be more clearly expressed by inverting it: email formatting has nothing to do with Markdown.

That's just as inane for the same reasons.

You’re both right. The original implementation was a superset of HTML. Do the lightweight syntax for the common stuff and HTML for the rest.

Yeah, that's what I feel gives markdown an edge over nearly anything else; markdown is adopting conventions that were meant to be readable without any kind of rendering. I can very easily tell what my markdown document is going to look like before I render it with Pandoc, because it's basically just taking stuff people were using with plain text that was meant to be read directly anyway.

I haven't used rST, but looking at the examples it looks considerably less readable out of the box.

Oh it's not that bad.

    * one
    * two
    * buckle my shoe

    | inspiring quote
    | - some famous guy

    foo
        a kind of bar
    bar
        part of a foo

    :red: stop
    :yellow: speed up
    :green: go

    - code:: python

    def fun():
        pass

    Go here_ for more info.
    - :: here: https://google.com

    My **strong** text is well *emphasized*. Very ``literally``.

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

That’s pretty much how I feel. When the author writes:

> This means you can extend Sphinx with new text objects! Say you that instead of an <image>, you want a <figure> with a <figcaption>. In basic markdown you have to manually insert the html

I can’t help but wonder what’s wrong with just writing HTML if you want those features? Why the extra layer?

Convenience? I have a "spoiler" role for rST, for example, which works like this:

    # state class to contain the counter
    class _spoiler:
        count = defaultdict(lambda: 0)
    
        def id(src):
            _spoiler.count[src] += 1
            src_hash = sha256(src.encode()).hexdigest()[:7]
            return f'spoil-{src_hash}{_spoiler.count[src]:03}'
    
    def spoiler_role(name, rawtext, text, lineno, inliner,
                     options={}, content=[]):
        src = inliner.document.attributes['source']
        html = (
            '<input id="{id}" type="checkbox" class="spoiler" checked />'+\
            '<label for="{id}" class="spoiler">{text}</label>'
        ).format(text=text, id=_spoiler.id(src))
        return [nodes.raw('', html, format='html')], []

I don't want to do that manually, and this lets me write :spoiler:`Rosebud was the name of his sled`.

Just out of curiosity, why not use HTML5's built-in details/summary tags (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/de...)?

These get styled such that they're black-on-black until you click on them. detail/summary doesn't work like that. Maybe with wild css hacks?

The author wrote an entire article explaining their use case which answers your question. Short version: they’re writing a book which they want to render to multiple formats with semantic linking between items and different rendering based on formats.

I get that, but why not use HTML as the base to render to other formats? I guess I'm not 100% clear what you mean by semantic linking and how could that not be achieved through HTML.

If I understand you correctly, you want to throw out rST, and just have users write HTML directly? I see two issues with that:

1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number.

2. HTML is not extensible in the way the author talks about. This is the "semantic linking" thing I meant. In rST, you can define entirely new top-level constructs: he defines an exercise which has a solution and will be a part of a solution list. The semantic linking part is that other parts of the document will refer back to these solutions. Some output formats will have all solutions inline, with the exercises, while other output formats will collect all solutions in one place at the end. HTML is not flexible in that manner.

What is extensible is XML. It's entirely feasible for XML to be the input, but for better-or-worse, most people are even more turned off by XML than they are by something like rST.

That's like saying why use C++ templates if you can just write the same function for every type that needs it. Now you don't need template instantiation!

The point is that it's objectively better when you want to separate the concerns of writing content and rendering it. It makes writing much easier and keeping the layout consistent as well.

Preserving the semantic content is helpful if you think you might want to switch the rendering later.

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.

> something HTML-based

Instead of HTML you can use XML to write structured documents. With XML you can define whatever custom tags you need with schema validation if desired. The advantage of this approach is you have full control over the input schema and output, but the downside is XML is much more syntactically noisy compared to Markdown or RST and you will need a script to parse & convert the XML to your preferred output format(s).

> Markdown or RST and you will need a script to parse & convert the XML to your preferred output format(s).

XSLT will happily output any number of formats from an XML doc. There's also a number of existing and very capable XML schemas for documentation like DocBook. You can even go from a lightweight markup like RST or Markdown to DocBook and then have an XSLT pipeline that delivers that intermediary to any number of formats. There's also very capable graphical editors that will spit out DocBook directly.

I find the aversion to XML very strange. It was definitely applied in some places poorly by products with "Enterprise" somewhere in the name but the language itself is very useful. The aversion to XML has led to a lot of work re-learning of the lessons that led to some XML features. It's also led to implementing XML features poorly in other languages.

Pro-tip: use SGML which has it all:

- is a superset of XML (XML is derived from SGML as a simplified, proper subset)

- can parse HTML precisely with all bells and whistles such as tag omission, enumerated attributes and other shortforms (which are based on SGML after all)

- can define markdown syntax as an SGML SHORTREF customization (note that SGML can not cover all of markdown syntax; for example, defining reference links somewhere at the end of a document and expecting SGML to pull a href URL into the place where the link is referenced won't work with SGML SHORTREF)

The combination of markdown-as-sgml and inline HTML or HTML blocks is particularly nice and predictable, and also informs further customization such as using entities (text variables), custom elements, and other advanced SGML stuff with markdown that comes up frequently as a requirement.

Once you get that far, XSLT is waiting for you if you need to render XML to HTML.

I don't think this is the case.

In python, rST is just one of many supported input formats for docutils: https://docutils.sourceforge.io/README.html#purpose

The entire point docutils is to parse formats and convert using an API: https://www.docutils.org/docs/index.html#api-reference-mater...

My beef is that it doesn't have an RST writer. What I want is a central hub where I can suck in documentation that was originally in different formats and then manually edit it in a format where I can capture essential semantics and then feed it through the system again to produce output documents.

If it had that it would be a 200 foot tall giant robot, as it is it's just another documentation generator.

rST and Asciidoc seem roughly equivalent in terms of capabilities. Are they roughly equivalent in terms of weaknesses and missing features, I wonder.

I think they're about equal, although asciidoctor has bold italics, which rST does not.

I am (was?) a committer to docutils (the main tooling for rST). One of the reasons I moved my tooling to md was because docutils was such a pain to work with (refusing to move to something like GitHub illustrates how hostile working with it is).

I can't test (no computer right now) but can't include directives achieve what you want?

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.

Great points about links, especially external links — it makes a lot more sense in the context of a documentation site where you might have the same external link referenced multiple times in the site, but you only want to have to update it once if it changes.

The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale).

https://www.sphinx-doc.org/en/master/usage/referencing.html#...

that is one of the things I miss most about writing in rST, for sure.

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.

Have you looked into mdBook? I haven't used it myself, but I've enjoyed the documentation of many projects that do and it seems really nice once you get past the point where a single readme file works well.

They also have some nice instructions on automated deployments.

https://github.com/rust-lang/mdBook

Thanks, but this does not seem to involve hosting? What I'm saying is, static site generation is no problem at all, because even without all the choices for frameworks, pretty much everyone has to speak at least one templating language and read/write both markdown and rst anyway. But it's surprising that writing your project docs and rolling your own static-site generator is faster than figuring out github-pages and/or readthedocs hosting from scratch.

For hosting static sites, I actually like AWS amplify, and integrating it with github seems currently easier and certainly more flexible than trying to use github pages. But I don't really want the hassle of a custom domain or a subdir on existing inappropriate domains for every new project I start.

This isn't about being cheap either BTW, I think it's important that self-hosting should NOT be the best way to get a friction-free setup for small-to-medium sized project docs. There's a major benefit just to the recognizable domains for github-pages / readthedocs, which is that I know I'm about to look at some kind of technical project documentation that is most likely a labor of love, rather than marketing fluff or a "sign up for the preview here!" bait and switch.

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.

You've provided a very simple example that can be performed easily in both Markdown and reST.

reST offers a lot of additional formatting features which are beneficial if you need them and cruft when you don't.

I first started using Github-flavored Markdown after signing up for Github in 2010 (possibly earlier under another alias.) I used reStructuredText for Python docs a couple times. I found the latter to have a much higher learning curve and I haven't had a reason to use it since.

In general, either will be simple as long as your input is simple, and they will become complex as soon as you want something complex — I am pretty sure people here bringing the pitchforks are really not even aware of how reST looks like in the first place.

But looking through examples at https://docutils.sourceforge.io/docs/user/rst/quickref.html#..., I really see a lot of non-simple stuff done in an obvious way too (block quotes, tables, bullet and enumerated lists, sections and headings, separator lines...).

By the time you got on the markdown train, it has already won out, and you've probably seen a lot more of it than of reST, even if MD still wasn't standardized. As a counter-point, having done lots of reST with Python docutils prior to 2010, I still mix up reST and MD — there's nothing intuitive about any of their special syntax, and our perception is mostly tainted with our prior experience. I've also written a lot of ASCII-only docs prior to either of those, and most people used ever-so-slightly different conventions there as well (somebody mentioned using /this/ for italics as well).

reST was standardized in the form of a Python PEP from its inception so you could at least rely on learning it once.

Edit: My ultimate point is that you (and most everybody else, including me) are using MD because it's more popular, not because it's "better".

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

Unreadable? No. Frustrating to type out? Yes. Underline style is annoying when editing, and even if you technically don't have to match the length you will still feel obliged do. Double backtick is just awful to write, annoying out of all proportion to how much extra time it actually takes.

I guess you must really hate the double * for bold in either.

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.

I echo your sentiments, but sadly the Asciidoc python compiler (as far as I can tell) is deprecated and no longer supported. I think that leaves Asciidoctor as the only mature compiler.

There's a spec being drafted, so hopefully that will spur some more action.

For my purposes, Asciidoc is the best markup with the worst tooling, and Markdown is the worst markup with the best tooling.

Oh yes, I could mot agree more. We moved from Antora/asciidoc to mkdocs/markdown. Overall the situation improved (better HTML, faster builds, syntax highlighting of code,...) but I miss how good writing in asciidoc was

I run asciidoctor's Docker container. It does what I want it to do without leaving a mess behind on my laptop.

Yeah a nice Rust or Go-based implementation of Asciidoc would be fantastic. Having to deal with Ruby and Gems is not fun.

That's a mountain of work though and even if there is a spec, at this point it's complex enough and the Ruby implementation is enough of a de facto spec that I'm doubtful you'll ever make it past "this behaves differently to Asciidoctor" territory.

Btw a more recent alternative is https://github.com/jgm/djot which actually does have multiple implementations and looks like a way better option than Markdown, but maybe not as powerful as Asciidoctor still. I haven't tried it.

the toc macro on asciidoc is sublime

:table-caption!: :toc: macro :sectlinks:

toc::[]

Except no one uses asciidoc either, and trying to manipulate it with Python is painful. Sadly (or not, depending on your opinion), the world has converged on md.

Markdown is definitely far more popular, but I see more book-length specification type documents written in Asciidoc. For example the RISC-V spec, or Ferrocene's Rust spec.

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.

Absolutely. I prefer rst for the use case of writing a technical book, because of the specific benefits I get from its additional complexity. My blog is still in markdown.

Having done a little of both, I find RST is faster just because I can lookup whatever syntax I need to keep going while with markdown I often stop to scream because I can't make it do what I want. Either is easy enough to understand when reading raw text - this is mostly about good style though, RST gives you more options for bad style that is hard to read.

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.

> do we have a language server that can look up available references, headlines, figure names etc and help you auto complete?

That would be a total gamechanger! Having the ability to do ref/doc links and not have to worry about stale topic headers is another thing I loved about writing in rST that I miss now that I'm back in markdown.

Yeah, the rst lsp server (esbonio) can autocomplete and jumpto references in your project. I believe the markdown lsp can do this too, but only to a limited extent.

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.

Exactly - does anyone (well, maybe the author does since he did use markdown in previous works) use "basic" markdown anyway? There are always some extensions (either front-text metadata or syntax extensions like this one) in the "interesting" apps. (The python markdown module API kind of feels like it's entirely about extension and only a little bit about actually parsing, but that did make it easy to add an `ASIN()` token for a review site without needing a preprocessing stage...) That does make it a little worse for interchange, but that's maybe less important for markdown anyway.

(Even with pandoc, https://pandoc.org/MANUAL.html#extensions lists a bunch of syntax for things like this, brought in from github, php, and other places - for the example above, `implicit_figures` and `link_attributes` are a good starting point.)

OK that specific example works, but what about his later problem vs solution one? One runs out of hacks pretty quickly.

Honestly I stopped reading article after this example. No, thank you. RST syntax looks confusing and overly explicit. I'd stick with MD thankyourverymuch.

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 can look at a rST file and read it, and I think you will have no problem reading every rST file I've ever looked at. Sure it will take you a few seconds to realize you can ignore various syntax things, but that isn't a big deal and then the whole makes sense. Of course rST gives a lot more options to write documents that are not human readable, but it isn't that hard to make them readable.

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

An interesting commonality among the three examples you listed: they're all designed for a world when computing was a more solitary activity than it is now.

For Lisp and Smalltalk, image-based development is a genuine hurdle in the modern world. It complicates many aspects of modern highly-collaborative software development, including version control and continuous integration. I think that the language's respective hacker ethoses might also be a challenge in light of how often people switch jobs nowadays. I haven't used Smalltalk for pay money, but my experience has been that initially getting settled into a large pre-existing Lisp project does take more brain effort than it seems to with a language like Java. (In the long run I'd rather inherit a Lisp project, but I also acknowledge that first impressions are important.)

And BeOS was not a multiuser OS and didn't seem to have a clear path to becoming one. I'm pretty sure the main thing preventing it from becoming as much of a cybersecurity disaster as Windows 95 was is the simple fact that there wasn't any honey in that pot.

This largely occurs because the only real spec of rST is the Python implementation. And tools written in other languages are loath to include a Python library just to support one document format. While writing a new compatible implementation is much more work given the larger scope than it is for Markdown.

So every language has a markdown implementation, but if you want to use rst in your Rust based static site generator or your PHP based CMS or whatever, it's a lot more work.

People don't add it because it is ugly and verbose.

And then people don't create any new format for its use case because it already exists.

Almost everything good we have only exists because some person irrationally decided to do it, against all common sense and logic.

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.

Yes but Djot is pretty good though! Wouldn’t call it informal nor bug-ridden, it’s well thought out and doesn’t have many corner cases:

https://djot.net/

Indeed; Github will now render TeX in markdown documents, eg when displayed as a repo's readme. Very convenient.

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 believe Mozilla uses rstcheck for linting, and it's actively supported.

https://github.com/rstcheck/rstcheck

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…

I had to scroll way too far to find this. All the arguments for RST are about how much more expressive the language is, how much care was taken in making it an abstract document tree. Yet there are simple trees you can't encode, even common ones that markdown handles fine.

I'm not using a language simply because it was aiming at something better, if it missed the mark.

Right, this is the one fairly clear down-side of RST, in practice I've found it's never been an issue - but it does seem like a strange constraint.

If you really want you can define bold italic text using some styling magic, but that's quite awkward.

> IIRC, nesting of inline markup is generally not possible. It works in Markdown…

How do you write xy in Markdown (without using HTML tags)?

Yes, and this sucks.

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.

Yep, it seems like the platonic ideal of a "worse is better" situation.

I do think this is, ironically, partly a documentation problem - when I last tried to create docs for a python codebase (several years ago), I found the rST docs to be sorely lacking in basic, introductory "here are the core mental models for how this works" sorts of content. Maybe the situation is better now? (Or maybe I just missed them, but not for lack of trying)

But I feel like then, it's obvious README.md prevailed and will continue to be the standard - you can use markdown for a very long time without ever reading any documentation at all. Worse is better, I guess.

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

Words are styled the way they're styled. McDonald is a proper noun with two capital letters, Mcdonald is simply not correct.

I'll note that you didn't manage your footnote consistently, since you spelled MediaWiki correctly, rather than spelling it wrong as Mediawiki.

For some reason, you decided not to do that with rST and LaTeX, without explaining why. Latex and LaTeX aren't even pronounced the same way, so I fail to see the purpose in your (inconsistent) stylistic choices here.

Why is your username not capitalized, Keybored?

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

Haha on one hand its probably Aaron Swartz's worst work. On the other hand, this is definitely the best reason to use markdown.

RIP

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

I have a customized version of pelican which is a python based static side generator. It basically supports this type of structure, except that in place of a physical separate meta-data file all the metadata goes in the front matter section at the top of the markdown file, and it gets stripped out of the actual rendered HTML.

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

> Well no, but "Markdown" is also a standard with more implementations you can shake a stick at

This ubiquity comes in large part from its lineage. Gruber based Markdown on the established cultural standards in raw text emails. The people who quickly adopted it where doing so based on familiarity.

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.

I've written a few Sphinx extensions ... it seemed OK to me, a bit awkward but long term - this is the kind of thing you do rarely & use often, so how nice it is to write extensions is barely an issue.

I think author should write HTML if they want extensibility so much. Not like RST is reading-friendly to begin with.

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.

Which is why I use rST - just as easy to write, but enough more powerful that I'm not left hanging when I realize I need to do something more complex.

> Documentation that is written is better than documentation that isn't.

I have to disagree with this. I've read too many out of date documents. If documentation exists that isn't correct it is worse than no documentation at all. The only useful documentation is documentation that is correct, easy to navigate, easy to search, and easy to update as the world changes (there might be more?).

Good documentation is better than bad, it is debatable if bad documentation is better than no documentation or not (in part because some bad documentation is worse than others).

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?

HTML is a bad choice - I want to be able to reorganize my site without have a million dead links. Even if I know what the correct organization is today, requirements will change and so in the future something will be wrong.

With rST I can link to a section and move that section to a different document and the links all still work (or if they don't I get an error for each and so I know where to look). With markdown and html I link to a specific document and since each is a document generator there is no warning if I typo the page name (there are a number of tools to look for dead links in html). With markdown I cannot link into a section of the page, only the page itself (some extensions to markdown allow this)

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 `` 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!

Out of curiosity, would you be able to write a parser that uses the markdown style for image links?

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.

Strange that everyone seems to think it's simpler, it seems might be a web-developer bias here.

I'm not a web developer and I don't find markdown especially easy/pretty/simple... I find it annoying when the same markdown can't be used in different places based on the rendering engine and there aren't standard ways to extend it.

Also, having trailing whitespace as part of the spec.. tsk!

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.

What kind of compliance? I’m working through the same thing right now and trying to decide between sphinx and mkdocs

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.

Sure, the markdown AST is its own thing, but no doubt its a isomorphic to an obvious subset of HTML and that's not a coincidence.

Moreover, you are missing Hillel's second point, which is that there is nothing like an "abstract node" syntax which can be used for custom extensions. Lisp has (NAME ...) and XML has <NAME>...</NAME>, and these are separate from the choice of NAME.

(GitHub-flavored) Markdown's one extensible thing is

   ```NAME
   ```

but this isn't so useful because the inside is unstructured text (on purpose). You want a custom node which doesn't escape everything within, so you can have more regular or custom nodes on the inside.

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)

One solution:

https://pandoc.org/

Or “how I stopped caring about doc formats”

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.

ORG's tightly integrated into emacs & it's ecosystem. It's fine but I don't think there is an equivalent to Sphinx for large cross referenced documents, with different outputs formats & support for translations (different languages).

Perhaps some of these things exist - I may be wrong, if they do I doubt the system is as mature or well supported as Sphinx's.

> 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 keep my journal in a blend of asciidoc and markdown. In asciidoc, I love xref soooo much, which lets you make cross-document links to .adoc files that still work after being translated to html.

But I'm so sad that asciidoc isn't supported by pandoc.

Right? So many features, and much easier to write than RST in my opinion. You can do things like dynamically reference other files to build tables:

  [%header,format=csv]
  |===
  include::tracks.csv[]
  |===

What about only including specific lines? Say from a log file or a separate piece of code? You can do that!

  [source,python]
  |===
  include::example.py[lines="1..10,15..20"]
  |===

Asciidoc solves nearly every problem I've ever run into with markdown and RST. I really wish it were more widely adopted.

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.

What are the objective criteria in that case?

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. <Michael Scott "nooo" meme>

While a tree datastructure like YAML (or JSON) can be mapped to a document (like HTML, or PDF), as demonstrated by the existence of the DOM tree and the (mis)popularity of XML, the one lesson we should have taken from XML is that it's awkward and you should not mix a tree datastructure with a text markup syntax.

Do not make humans have to construct their documentation as a tree first. Let them do in a free-flow way, with markup, and have tools internally convert it to a tree.

We've emerged from 20 years of XML-as-a-human-readable-datastructure dark ages. Let's not then make the opposite mistake.

What's the YAML syntax for "That's a _weird_ idea, [YAML](https://yaml.org/) is a data serialization language"?

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.

No offense taken! Sphinx gives a lot of options for customizing pdf formatting, but I'm not thinking about that just yet. Step one is to get the book's content done, step two is to revise the content, step three is to revise it again... Getting it to look good is on my list, but ultimately a problem for future me.

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

Grandma’s doc may not be readable in 30 years. I can look at basically every text file written since ASCII came along with standard tools. Also, since Grandma isn’t a programmer, she’s probably not collaborating on her doc with a bunch of distant people using a version control system with patch requests.

Shiny tools are nice when it’s only you and you don’t need to keep the results forever.

Word sucks if you want consistent formatting. It has styles, but they randomly glitch out and can't always handle everything. I want docs in HTML, not PDF, and definitely not DOCX. The issues some programmers have are issues with content, not formatting.

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

Reply on news.ycombinator.com