This is the reason that most projects I've been a part of end up on Sphinx/ReStructuredText as the docs generator of choice - has a huge installed base of users and developers spread across many projects.

Markdown is great for a simple readme, but once you start needing larger more structured docs, or want output formats other than HTML, it just falls down.

On the whole, rST for sure has the right stuff. Having a document model and a nice standard extensible mechanism for syntax really helps. It's been my favorite.

But even when writing my last paper I used Markdown (+pandoc) because I had a coauthor and Github et al. have made it more familiar to so many more people. Maybe in niches like the Python community but it's a distinctly minority option, at least where I've worked.

Is there a formal spec for ReStructuredText? Not every project would want a dependency on the Python ecosystem.

> it just falls down.

Oh? These are written in Markdown and typeset using ConTeXt:

* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... (see 9.9.1)

* https://www.docdroid.net/eGHQ6O7/autonoma-pdf (see emojis and speech bubbles in chapter 2)

* https://impacts.to/downloads/lowres/impacts.pdf (99% pure Markdown)

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... (technically XHTML, but can be converted)

> This has been somewhat ameliorated by the rise of CommonMark, which aims to provide a more formal specification for Markdown, and the adoption of CommonMark (albeit often with some extensions) on some popular social platforms

They mention CommonMark as a popular specification

What's puzzling is that the creator of Markdown wants it like this, and actively resisted endorsing an official standard. He got into a fight with Jeff Atwood from Coding Horror / StackOverflow because of this.

He didn’t like when CommonMark was named “Standard Markdown” or when it was renamed “Common Markdown:”

https://blog.codinghorror.com/standard-markdown-is-now-commo...

It also sounds like he ignored an invitation to join the effort to create what became CommonMark.

Since that was as close as anyone came to standardizing, ya it seems reasonable to conclude he’s fine with the ambiguities.

Yes, that's the conversation I meant.

Gruber got irritated by even attempting to get his opinion on this effort. Very, very weird.

Should have called it Common AppleFan.

Much of the community has coalesced around CommonMark.

You'll still find Markdown implementations with a "don't care" attitude, but if an implementation targets any specification at all it's going to be CommonMark, a superset of it, or (more rarely) a subset of it.

I'm getting a sense that it's standardising around CommonMark.

there's still at least four marksdown that i can think of offhand, and likely far more.

There is CommonMark, but even that is very opiniated.

One of the issues is that original Markdown used tabs everywhere, but people started using spaces, but some implementations choke down on them.

The biggest issue in Markdown is that whitespace is significant and important; and there are tons of weird edgecases of all the various rules clashing with each other.

Even CommonMark has some weird unspecified edgecases.

I was briefly involved with a Markdown parser implementation… it’s really really hard to parse MarkDown. Not sure if harder than to parse HTML, as I did not do that. But it’s still really really hard.