Markdown's Big Brother: Say Hello to AsciiDoc

> If you’ve been relying on Markdown and occasionally fighting its quirks, AsciiDoc might be the structured, fully-featured alternative you didn’t know you needed.

No, I'm afraid it's the format I know I don't need. At least not for the kind of things I usually use markdown for.

Readme files, technical documentation, moderately complex websites with templating and rendering engines - markdown works just fine. Sometimes with a custom `|||warning\n...\n|||\n` thrown in to render something in a box with a red border.

I get that there's a market in the space occupied by TeX, Typst (underrated IMHO), and possibly MS Word or Quark Express (for non-techies). Libreoffice is great in theory but, again IMHO, "eh" in practice. That market is generating book-length documents with all the cross-references and other features that needs.

That said, Robert Nystrom of "Crafting Interpreters" managed this just fine with markdown and a few custom scripts: https://journal.stuffwithstuff.com/2020/04/05/crafting-craft... , https://github.com/munificent/craftinginterpreters/tree/mast... . This is how those famous 10x writers/programmers work, I guess.

Asciidoc is Markdown's big brother? I'll carry on playing with the little brother, thank you very much.

Also the whole page is an ad for their own editor tool. $9.99 per month so you don't need to use your own editor and unintuitive tools like (gasp!) the terminal.

As is org-mode. I think Markdown is one of those VHS vs Betamax kind of situations where it was just lucky to get the traction that its competitors didn't.

> Other than inertia

Why does there need to be something else? That’s a powerful reason.

Markdown is subpar and has an awful steward—as evidenced by all the different “flavours” and degrees of support in existence—but we somehow made it work in a jumble of hacks and that’s what we have now. It’s crummy but gets the job done.

Even if AsciiDoc is technically superior, which it probably is, is it superior enough to justify the big players implementing and pushing for in more in places regular users have access too?

The problem with asciidoc is that it doesn't support nesting. Markdown allows you to nest constructs as much as you want using syntax that are easy to use for both humans and documentation-generating applications.

The asciidoc developers don't seem to consider this an important issue: https://github.com/asciidoctor/asciidoctor/issues/1121

While asciidoc has some nice constructs, this made it a no go the last time I was looking for a documentation language.

Once I felt that Markdown wasn't enough for documentation and Asciidoc seemed to be a good alternative.

I tried to rewrite it to AsciiDoc, but there was some unexpected ugly ess. Iirc e.g. lists. It bothered me so much, I switched back to markdown.

Today I reach for Typst when I need more than Markdown. Biggest caviar there is that html export is still wip.