> still markdown just isn’t powerful enough for anything non trivial

I see this sentiment a lot, and my reaction is always, “Sure it is, with asterisks.” In the past decade I was the primary author of the RethinkDB documentation, a senior technical writer on Bixby’s developer documentation, and am now a contractor working on Minecraft’s developer docs. All of them were large, decidedly non-trivial, and Markdown. Microsoft’s entire learning portal, AFAICT, is in Markdown.

And the thing is, each of those systems used a different Markdown processor. My own blog uses one that’s different from all of those. According to HN, I should be spending virtually all my time fighting with all those weird differences and edge cases, but I’m not. I swear. The thing about edge cases is they’re edge cases. I saw a “Markdown torture” document the other day which contained a structure like this:

    [foo[bar(http://bar.com)](http://foo.com)

The asterisk is that almost any big docs (or even blogging) system built on Markdown has extensions in it, which are usually a function of the template system. Is that part of Markdown? Obviously not. Is it somehow “cheating”? I mean, maybe? At the end of the day, 99% of what I’m writing is still Markdown. I just know that for certain specific constructs I’m going use {{brace-enclosed shortcodes}}, or begin an otherwise-typical Markdown block quote with a special tag like “%tip%” to make it into a tip block. Every system that proclaims it’s better than Markdown because it allows for extensions, well, if you take advantage of that capability, look at you adding site-specific customization just like I’m doing with (checks notes) Markdown.

If reStructured Text works better for you, or AsciiDoc, or Org Mode, great! Hell, do it all in DITA, if you’re a masochist. But this whole “this is obviously technically superior to Markdown, which surely no one would ever do real work in, pish tosh” nonsense? We do. It works fine. Sorry.

> {{brace-enclosed shortcodes}}

I haven’t checked if any of the details have changed any time recently, but Zola does this, and I had a rough time with it because of the interactions with Markdown rules around raw HTML and escaping and such. I have worked to forget the details. I reckon Zola bakes Markdown in too deeply, and it’s a pain. Especially because of indentation causing code blocks, that’s one of the biggest problems with extending Markdown by “just writing HTML”.

markdown is great for a single short page. It doesn't have good links to the middle of a page (some extentions do but not the popular ones), nor can it generate tables of contents, indexes, and the other things a large site should have. Rst will do all that and because it is a site generator if you reorganize the links get fixed - or at least you get a warning onia dead link.