Many years ago I introduced it at a newspaper full of OG reporters who were a little nostalgic for the clatter of typewriters and the kid who would run the drafts around the newsroom.

On the first day they thought it was weird. On the second—and I'm not exaggerating, it was 24 hours—they loved it, because unlike MS Word/most WYSIWYG junkers, it did exactly what they told it to, without fussy formatting or invisible characters.

I've done this several times since, with all kinds of non-technical users who would never, ever tolerate something like LaTeX.

I have some clients where I will send docs in MS Word/PDF format, but that kind of proves the point: the recipient sets the format. They may not explicitly say anything, but I'm not going to send something if there's a risk of receiving a "how do I open this?"

Also, code blocks are the worst example of it's limitations: just use backticks. Sometimes I want to have a big table or diagram and find that Markdown (/Obsidian) doesn't quite scratch my itch, but then there's always HTML...

I like to think of markdown as a high level markup language that gets compiled down to html. There is always a fallback to write html directly in markdown.

I think that is unlikely to happen any time soon.

The problem is there isn't any kind of authority that can improve it. The closest we have is commonmark, which is more of a deacriptive specification rather than prescriptive.

I also doubt, that Markdown will be able to be extended with the same "ease" HTML has been extended. Markdown does not have a systematic syntax like HTML does. It is not parser and machine friendly. It may be human friendly, but that doesn't make it easy to extend. In HTML on the other hand, one could, theoretically, just come up with a new tag name and introduce a new tag. Mind, we are talking about using both formats for writing a document. Of course Markdown doesn't have the same burden of already being the workhorse of the web and being directly interpreted by browser rendering engines. That however is an aspect that resides outside of the actual format considerations.

We already got tons of Markdown dialects and most of them don't gain particularly much traction, because they are only supported in niche tools. The only one of them that could be considered standard is maybe common mark, with its extensive test suite. Specialized ones like Pandoc Markdown for writing papers exist, but will most likely never leave their niche.

What I could imagine is, that maybe the changes from dialect to dialect could be outsourced into "extensions" and then one would need to pick "syntax conflict free" extensions. But since the format itself is kind of ad-hoc, and not systematic like HTML with its tags, it seems also unlikely, that such an extension system would work well.

That is well known and I am sure the author is aware of it. The problem they are describing is not whether HTML is technically allowed inside Markdown. It's that when you are writing Markdown, you are writing Markdown, not HTML, and that comes with some problems.

> It is perfectly capable of what the author claims it isn't.

In theory, yes. In practice, using Markdown becomes much less appealing once you start dropping raw HTML all over the place. The whole point of choosing Markdown is that you do not want to spend your time typing <p>, <a>, <li> and the rest. You want to write in Markdown, with only occasional HTML when absolutely necessary.

That is exactly where the author's complaints become relevant. If the solution to Markdown's limitations is routinely switching to HTML, then the argument becomes circular. If you are expected to write HTML to address the author's complaints, why bother with Markdown at all? If the answer is just "write HTML", then you may as well skip Markdown in the first place.

AsciiDoc lets you mix and match however you want. Or, put differently: AsciiDoc's superiority over Markdown extends even to being better at shelling out to HTML.

Footnotes are the only not always included extension to mmarkdown I need for slides or argument flows that are not killed by sidenotes, and some sites and toolings support that in markdown.

Even table of contents is not a problem, so what else is left? Formula setting? Buttons for UI vs function? Buttons plus Inline JS for step by step state modification?

I am not programming, I want text and something to be easily pasted into Word-like rich text, which seems to be the default text editor for emails for 90% of the population.

Reddit surely doesn't, and I'd be very surprised if github did.

In practice, in any place you want untrusted users writing markdown stuff for formatting, you cannot allow arbitrary HTML for security reasons.

Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?".

It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be language that will serve both of those use-cases very well.

"Markdown is not great for writing complex documentation. Why not use XML instead?"

Can you provide more info about how exactly DITA+tooling fell on its face ?

To me, Typst is the 'weirdly missing' option here. I really see it as the most promising successor to LaTeX, which is not something I say lightly given that I spent years scoffing at the idea of Typst ever displacing LaTeX in my life.

I also have a philosophical issue with writing documentation in TeX: TeX is a typesetting program, i.e. it’s a presentation format meant to look a certain way on a page, while documentation should be agnostic to appearance as much as possible. But that’s more a personal objection.

Long ago I've read a study somewhere that people using LaTeX take more time and effort to accomplish same tasks compared to MS Word, but they are more happy about the process. Seems to match my impression that LaTeX is "by tinkerers, for tinkerers".

I like RST a lot for Python documentation, because of all the directives for types, admonitions, and lots of domain-specific stuff. I wouldn't use RST if I'm writing a book, or a research paper.

In the same way, Typst looks like a great candidate for those last examples, but is likely unsuitable for documenting a library written in Python.

1. typst only really has pdf output at the moment 2. so much less tooling available (linters, site builders, converters etc) 3. much less of a markup format, extremely tightly coupled to a specific tool (typst compiler)

again, love typst, but it has (atm) so much fewer applications

The same is true of Markdown (the canonical parser being John Gruber's at https://daringfireball.net/projects/markdown/) but that didn't stop third parties from extending it in their own implementations. For example, canonical Markdown doesn't support tables at all, but GitHub added custom markup for tables to their parser ("GitHub-flavored Markdown") and it became a de facto standard.

That said I am not sure what the solution is to that since your docs may need structure my docs dont need. Therefore you cant solve the "semantic" outside of a "namespace" of what you agree in your organization.

E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.

So to go full circle... you are right just use HTML. After all it's semantic isn't it ;-)

It wold be nice to show the starting list of files, a command, and the resulting list of files. It would also be nice to maybe color-code source and target files for each step, both in the command and in the listing. It may also help to typographically distinquish base files that are written by hand and generated ones. A few pictograms to tell apart files and directories would also be useful.

And it would be nice to somehow keep this a single process so that a command references a source state and produces the target state and the list of files is computed automatically.

(Doing this right now with XML and XSLT, targeting PDF via XSL-FO. Drew pictograms in SVG right in the XSLT. Haven't got to the automatic part yet, just got an idea that this is a natural way to go.)

I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file.

You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.

The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.

You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech.

I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: https://adammonsen.com/post/2122/

Most of the formats came out satisfactory, but there were some gotchas. https://github.com/meonkeys/shb/#%EF%B8%8F-book-formats lists some, and https://github.com/meonkeys/shb/blob/main/issues.adoc has more. Translating from English to German went OK with asciidoc, but it might have been better with docbook and standard translation tools for working with .po files.

Here are two examples where the author used Markdown and the result was beautiful and successful (although layout for printed editions were done with extra/other tooling): http://gameprogrammingpatterns.com , http://www.craftinginterpreters.com . I'm curious if Bob would/will use Markdown for his next book. My process is different than Bob's... I didn't need literate code and I didn't want to do _any_ layout/pre/post-processing, even for print. Asciidoctor worked for this, although there were some compromises (see my links above). Print-ready layout is a lot of work, however you do it.

Is this your first book? Do you have a publisher? Will it be printed on paper? Do you have a developmental editor / proofreader / etc? Do you have a plan for what you'll do after you publish e.g. talks/promos/tour?

Contact me if you want to chat. I'm happy to share my war stories. And good luck!

- table of contents

- automatic chapter and section numbering

- cross references and automatic tracking of figures, tables etc.

- different styles besides blockquotes such as info sections, warnings, tips

Imho, cross-referencing chapters, pages, figures, tables and the lack thereof in Markdown is the first and most important thing to check how you would like this to be solved.

But it's explicitly targeted at technical documentation. If nothing else, searching for DocBook alternatives might give you some ideas.

AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended for LLMs is a side effect of that.

You can write dev docs for humans and still want machine readability (without caring about whether some LLM can make sense of the docs).

Machine readability is how you repurpose your own documentation in different contexts. If your documentation it isn't machine readable it might as well be in a .doc(x) file.

> That <Command> tag isn't Markdown at all; it's a React component.

Turns out he's in his 40s, so he lived through ms word, front page and the JavaScript wars; this is almost certainly satire