Last year we changed the source format for MDN from some extremely messy, WYSIWYG-authored HTML to something that would be easier for authors to use. We considered Asciidoc and reST, and despite its limitations, we chose Markdown (GFM specifically) for two reasons:
1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.
2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.
One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.
I work in an academic setting and I can second the sentiment. For a while, we used reStructuredText for writing the teaching materials. Every so often I would have the students that would get inspired to contribute something to the teaching materials, but would subsequently get demotivated by having to learn the rST syntax and tooling.
After a few years, I gave up and switched from rST and Sphinx to Markdown and MkDocs [2]. We addressed the limitations of Markdown with PyMdown Extensions [3]. Still haven't looked back; for our specific use case of writing (computer science) teaching materials, Markdown is a better choice than rST.
Thanks @vedranm! I especially like your side-by-side comparison of the process of contributing using Markdown versus reST. It really encapsulates the difference that reasonably seamless tool support makes. I need to look more into MkDocs...
You are welcome. I have no connection to its development aside from some minor translation updates and bug reports, but I can only recommend it.
What I like is how easy it is to host MkDocs on GitHub Pages via built-in support, but you can even make it behave like Jekyll with GitHub Actions. Shameless self-plug of another blog post: https://gaseri.org/en/blog/2022-11-01-publishing-material-fo...
You made the right choice, rst is not user friendly, even for tech savvy people.
I'll take the opportunity to do a shameless plug for the amazing "Markedly Structured Text", or MyST, a markdown flavor that is both easy to write like markdown, and expressive like rst.
Basically, if you know markdown, you can write decent MyST already. In fact, any markdown is valid MyST and .md is a valid file extension for MyST.
Once you want more, the syntax offers richer construct, but still easy enough to use.
I wanted to love asciidoc because the format rocks, but it never took off and the tooling is still lacking. MyST piggy back on markdown ecosystem, this is less of a problem.
Also, the devs behind it also have a very good track record at creating a good FOSS ecosystem.
The “one more backtick” syntax is a very early Markdown feature explicitly mentioned by John Gruber (originally only for inline code, of course). It might even be in the original “spec”, I don’t remember, but it dates way back and is implemented by virtually all half-decent Markdown parsers. It’s one of the least utilised feature, however, so huge kudos for MyST to clearly explain it and raise awareness.
I still cannot believe MDN decided to abandon web standards for the garbage that is Markdown. Worse yet, they seem proud of themselves for doing it.
Rather than actually solve the problem of filtering WYSIWYG input/output, providing a solution for creating easy to create and maintain semantic HTML, Mozilla shunted it aside and now use a stack of custom tooling and libraries and yet another Markdown-alike variant text format with their own scripting embeds and then patted themselves on the backs for all the effort they "saved".
Mozilla is supposed to be the standard bearer for web standards. It's sad to see that bunch of myopic techies decided to go with a trendy solution that just trashed a core principle of the organization (#6) for one of its most important products. It set an example others are now following, and as a result, MDN put the web back probably two decades.
Rather than embarking on something that proved to be hard by decades of trying, or inventing something complex and unique, Mozilla took a less powerful existing tool, very simple and well known to every contributor.
They acted as if they tried to make it simple and easy for the community to keep MDN up and up to date. Outrageous!
Well, by the book and its origins, there is no improvement just because in Markdown you can use any HTML. Markdown itself is part of the try when you follow the path of its history and when marketed as a subset, it means (and that approach may be valid), let us go back and reduce to the early set of HTML tags.
I wrote enough basic HTML tags back in 1995 to say that writing _this way_ is way more ergonomic than <i>this way</i>.
The thing is that HTML (and SGML) was invented, but Markdown was discovered as a set of best practices through decades of text-only mailing lists. This is something that many people found natural enough.
Sure, if adding symbols to text is enough, why do more?
It's bending perhaps history of mankind in my book a little too much, saying the author of Markdown has discovered that and not lets say, someone else the "one or other" millennia earlier.
And writing on the computer is commonly the least ergonomic form of writing at all.
I've upbooped this perspective but I disagree. Markdown trivially compiles to HTML and is justifiably loved (aside from the proud markdown haters, old and jaded and scarred by it not working for their weird usecase that one time), and you haven't suggested an alternative which addresses the problems they had with the mess caused by wysiwyg output. But maybe you have a better solution? Beyond the entitled expectation that it's someone elses job to fix it.
Also #6 of their manifesto is about interoperability. Markdown is a great choice for this if you are consistent in your approach. No lock in, human and readible.
What's holding the web back by 20 years are </closing tags>. If it wasn't for them, CMS would not have had to be invented, and everybody would be blissfully authoring effortlessly semantic hypertext like they do with Markdown now.
Heh, you're not wrong. I've thought for a while there should be some sort of valid, but easily hand-written version of HTML5 where any text between two newlines is considered a paragraph. That alone would go a long way to making HTML more text-editor friendly.
Other block-level elements would auto-close either at a new line or when a new block tag starts, headers would automatically create <sections> that end when a new header appears, and inline elements would end at the next space, newline or generic end tag like </>, so they could be nested.
A lot of this is done already in the browser. A valid HTML doc just needs a doctype, title and a body tag and the spec specifies all the rest will be filled in automatically. The spaghetti logic employed to add in missing closing tags to keep pages looking decent is mind boggling. Seems like there could be a few additional spec rules and then plain-text HTML would be just as easy to create as any other markup.
1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.
2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.
One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.
If you're interested, we blogged about this project: https://openwebdocs.org/content/posts/markdown-conversion/.