Return to Structured Content

My biggest frustration with modern docs is that much of the industry standardized on Markdown.

And Markdown isn’t semantic. A keyword, a term, a “first use” item all don’t exist. You mix presentation with meaning rather than separating.

XML for docs wasn’t fun but it was structured. You could denote terms. You could have actual admonitions.

And so the solution seems to be hacks that turn Markdown k to structured docs, embedded HTML spans with classes, and….MDX.

I’ve done it all. It stinks. I’ve been deep in Goldmark and Remark, converting Markdown to trees so I could render things.

There are alternatives though.

I think with AI, we are going to need semantic structured content again.