Having said that, https://docs.microsoft.com 's flavor of Markdown does allow for embedded HTML, like GitHub's and enough pages still use that feature that the conversion to Markdown is arguably incomplete. It isn't a big issue in practice, however; you can update markup from HTML to Markdown along with your other changes.

* As a recent-past engineer on the Windows team, I have a rather lower opinion of Windows API docs than you. :) The Windows developer platform has not had enough dedicated technical writers for years; our developer content teams are mainly editors of engineer- and PM-written original docs, which can lead to API doc sets with badly written pages, important missing information, or references to Windows-internal developer tools. I tried to channel my frustrations into correcting and extending my coworkers' writings, or into gently asking them to fix their omissions when I didn't have the free time to spend on the needed research.

I'd suggest they start with a toy I made a while back, Dumbdown as a base, and evolve from there: https://jtree.treenotation.org/designer/#standard%20dumbdown

Any form of structured information, for example API functions and their argument types, properties of a class, or tables of historical compatibility, is already stepping outside Markdown.

You're left with either writing everything out in text and having error-prone parsers cross-check pages against each other, or badly cross-referenced information that goes undetected, or using something that is Markdown plus additional markup for semantic data.

Other things that are critical features for development documentation, like tables, are extensions which may or may not completely break if you ever change your Markdown renderer.

If you need more typesetting control than what Markdown allows, dropping down to HTML is always an option.

To the second point, while it's possible that content could render differently if you change renderers, I would presume the folks at Mozilla are aware of this and won't do it unless it's absolutely necessary.

Do we actually know which renderer MDN is using? I don't see this mentioned in the post. I would argue that although alternate implementations exist, Gruber's `markdown.pl` is Markdown (whatever it does, warts and all) and deviating from it is generally a bad idea if you can avoid it.

Is it? In the public setting? HTML comes with things missing from Markdown that you want, sure, but it also comes with a full scripting environment, the ability to arbitrarily inject code and so on.

If you can drop to HTML, you have to have a sanitiser process. So then you're dropping to some-unknown-subset of HTML if the process is automatic - or you've failed to reduce the amount of effort being put on the editors if it's a human one.

For a place like MDN, this really isn't a problem.

> If you can drop to HTML, you have to have a sanitiser process. So then you're dropping to some-unknown-subset of HTML if the process is automatic - or you've failed to reduce the amount of effort being put on the editors if it's a human one.

I presume Kuma had - and Yari will have, if it doesn't already - some way to prevent unsafe injection and other dangerous things.

This isn't to say that the issue doesn't exist. Instead, I would expect it to be the exception rather than the rule. After all, Markdown and its derivatives owe their existence to this very phenomenon.

The language of last resort, if you will.

This is where is becomes useful to have tools that can generalize things. For example, say you link to another page in your documentation repository, in Markdown, you create a link either with an absolute or relative path, specifying the filename and optionally anchor on that page. Now later down the road, you edit the folder hierarchy, or rename a page, you will now need to find all references and update them manually.

Something like ReStructuredText has the "interlink" module, which allows you to modularize your pages, and use symbolic names instead of the relative or absolute path. Now, there are pros and cons to each approach, i.e. if you have a good set of tools, doing a global search and replace across documents can deal with this too. But having the flexibility of things like symbolic names and macros can make things much more manageable.

Of course, this is a double edged sword, in that you can customize, create macros, until you now have a monster in of itself, but that can be said of any tool.

I tend to see Markdown as perfect for standalone documents, and its especially good for formatting internet comments and the likes.

Tools like DocBook and other XML processors attempt to provide the maximum amount flexibility, and the cost of a steep learning cliff and lots of boilerplate, but if implemented well, it can allow things like conditionally including parts of documentation based on tags, or output formats, but definitely requires extensive tooling as opposed to Markdown and other formats that are meant to be readable in their source form.

with this arrangement, the character is leaning away from and pointing away from the words, and scaling down the character has made it difficult to make out the details of their pose (is that a hand? is the face empty? etc.).

The previous backend was codenamed "Kuma" and was represented with a bear, but wasn't displayed anywhere on the actual MDN platform.

Yari is a codename for the effort to move MDN closer to a static site architecture.

I think this is why a lot of sites take markdown, then add their own extensions, like how there is "Github Markdown" among many other flavors. That's definitely one route, but I see something like ReStructuredText or Asciidoc as more mature and interoperable, while still being relatively easy to master in the same way as Markdown. Since they can both produce docbook output, vastly easing any migrations in the future by adhering to an industry standard.