It's interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!

> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices.

This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain in order to re-create 'the semantic web' - a flawed concept that has failed to catch on.

If the LLM needs context on content that humans don't need, the LLM needs fixing, not the content.

> With Markdown as your source, you can't easily go to another format.

File->Print->PDF.

Was that hard? (I admit it's still bizarre that Chrome puts 'Save As PDF' under Print).

(Apparently you can also go via LaTeX if you love a CLI)

Markdown won. Simplicity always wins. Markdown is now the de facto documentation format, for better or for worse.

Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great.

For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me.

But in the end, no markup language will make you write better. It’s kind of like saying that ballpoint pens are limiting your writing, so you should switch to mechanical pencils.

This article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.