Markdown Is Holding You Back

By suggesting DITA as a valid alternative to Markdown, for any use, this has so completely lost the plot that it blows up whatever credibility Brian might have on the subject. It's disappointing, because I know of Brian and otherwise respect his work.

Short of writing in raw Postscript, I can't think of a more completely different set of strengths, audiences, and applications. I had to get to a company with more than 5,000 employees, 20 product lines, and 5 required i18n locales to find one where the overhead, god-awful ergonomics, and half-broken tooling of DITA were appropriate for the scale of the work _and also_ resourced enough to paper over every miserable facet of its implementation.

If you're using Markdown today _at all_ for a task, DITA isn't appropriate for it. If DITA was appropriate for the task, you never would've picked Markdown to accomplish it to begin with. Don't waste your time with it either way.

Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/warning boxes, lists, code snippets with syntax highlighting, header/footer, etc in literally minutes. What else do you need?

The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste markdown.

It's one of those good enough things where the things it doesn't do are outweighed by the notion that you can just use it pretty much everywhere.

It's a Betamax vs VHS type discussion (both are at this point obsolete and forgotten). HTML used to be pretty limited as well compared to things like SGML or any of the wonderful things people used for structured documentation in the eighties. Most of which are long forgotten. It still is pretty limited compared to those probably. But the point with HTML is that that's what browsers supported and not other formats. Many of the limitations were addressed over time.

Markdown could be improved in a similar way over time. We have ambiguous standardization, lack of features, mutually incompatible implementations, etc. The whole thing actually resembles HTML4 before people started addressing such concerns. Evolving Markdown seems like the easier path than replacing it with something else.

People keep reinventing LaTeX, but poorly. Most of the issues described have already been solved by it at least 20 years ago, especially the semantics part. The tooling is mature, well understood and supported on all operating systems.

Eh, we had plenty of such structured document formats in the past. Markdown has won simply because it's much less hassle to write while still being readable without a specialized viewer. Markdown is exactly at the right sweetspot.

I am surprised TeX [1] and LaTeX (pronounced tech and lay-tech) are not mentioned in this post. When I was a physics undergrad it was required that we wrote our senior thesis in it as well as any studies we meant to publish. Interestingly, my lab worked closely with a lab from the chemistry department and apparently their standard was MS Word docs. I was given to understand that this setup was fairly universal for both disciplines.

Latex seemed arcane coming from the background of HTML but it was pretty easy to pick up and is human readable.

Aside from the markup language itself, what is cool about TeX is its versioning. Since the idea is that at some point it does meet all of its goals it is essentially approximating its own perfect form. As a result as it gets closer to that goal its version approaches the value of Pi [2]. The current version is 3.141592653.

Tex has been around for 47 years so if you are looking for stability, look no further.

[1] https://en.wikipedia.org/wiki/TeX

[2] https://www.preethamrn.com/posts/piver

P.S.: manpage format is also quite simple to learn and it is always a really good addition to any CLI tool.

The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. Markup formats in my opinion need to be defined in terms of a proper grammar, so that we can easily adapt that grammar in any programming language to build a parser and have support for that format in another language. The Org format in Emacs also suffered from this, but now there is an effort to make a grammar for it, I believe.

That said, I have used reStructuredText for writing a technical master thesis, and for that it worked wonderfully. If you buy into the ecosystem or use Pandoc to convert to LaTeX/TeX, and build a PDF or whatever you need, it will work well. But if you want to use it as a basis for HTML pages from other languages, which don't have a parser for reStructuredText, then you are in for trouble.

I'm surprised Pandoc markdown is not mentioned. You can make that semi structured quite easily, and write your own transformations using lua. It's powerful enough to write math papers and export into both pdf and html.

Asciidoc corresponds directly to DocBook XML. They're two formats with exactly the same semantics.

> Markdown Lacks the Structure You Need

The problem is, I always need more structure. Give me some YAML and time and I'll make hell (not a metaphor, I'll concoct hell itself on it).

Markdown keeps me honest.

I'd rather use Markdown for writing and even user submitted content whenever possible instead of gag HTML or some other overcomplicated markup language. Sure, there's various different flavors of Markdown, but on average it's better than overcomplicated attribute ridden XML or even XSS prone HTML (where nobody even knows what section is and everything ends up being a div).

Just give me a good enough baseline, that's it. Markdown is close enough to that for now. I don't need that much semantic meaning in the text. Something like mdbook (https://github.com/rust-lang/mdBook) is more than enough for my needs, compared to shipping docs in once again, gag DOCX files and PDFs.

Good that there are solutions for more advanced use cases, though, but be careful with that complexity where you don't need it.

I've never struck any off these problems, and in order to use the tools he suggests I'd have to switch out the systems I use that just support markdown

I sometimes make documents that require more complex formatting, so I use html after 20 minutes fucking around in word and getting angry

Tried and trusted process

The tenor of the article is more like: Markdown is holding LLMs back. And it assumes the semantic enrichment comes for free. While I agree that other formats allow for that and it's nice to see the solid options: nope, nobody in our team has the time to do such a chore and we are fine with the information we leave for each other.

It's analogous to the whining of the semantic web folks. The semantic web hasn't happened as a whole. Same problem there: who would curate all the data?

I believe that Markdown shines because it is literally human language. It’s the equivalent of tearing a paper sheet from a notebook and writing stuff down. If I wanted formatted, semantic writing, I’d use LaTeX

I recently moved my personal writing to John MacFarlane's djot. It's a markup language that grew out of his markdown improvements blogpost, where he explored the issues, and possible fixes, he discovered while creating the common mark standard.

I've no regrets since then

https://pdx.su/blog/2025-06-28-writing-in-djot/

Uhh isn't the main strength of md that it's human-friendly to write? Same for yaml. In both cases, dramatically worse for processing, strictly weaker for semantics and rich formatting... And also doesn't make you want to kill yourself when you're editing it by hand.

I prefer writing Markdown for notes, e.g. in Obsidian, I think it fits very there. Because now you can easily take your notes to most other note-taking programs, and letting AI interact with these files also works great.

If I needed more context / am writing a paper I'd choose something like Typst, but usually I don't need the additional overhead.

(Btw: The author has a great name!)

You lost me at, "XML is not that bad if you are already doing <x>". Verbosity is insane, attribute vs element freedom induces crowd madness. But I do love the data-visiting parts, why can't they somehow get that into Markdown.

We found Markdown with directives[1] worked well enough for us.

[1]: https://talk.commonmark.org/t/generic-directives-plugins-syn...

[delayed]

Being held back is the point.. WYSIWYM is a better ideal than more fonts, but it still tends towards trouble. It is hard enough to get engineers to write and maintain small amounts of correct comments without adding boilerplate metadata. I think everyone on this site is familiar with gripes against Jira but they are supposed to take a brain holiday when evaluating documentation mediums? Who is going to make sure previous and next topic are correct after the addition of a new topic? The great thing about absent fields is that they don't end up with bad content.

Not at all. I use to maintain myriad of packages with restructured text, asciidoc, XML, perl pod and tex, but markdown all supercede it.

I could easily represent the long word spec for the DWG format in markdown with gh tables, rendering it to pdf, and it's even better than the original word. Just to represent our diffs.

I could easily produce C++ technical reports in markdown, rendering to pdf and HTML, which was perfect.

The rST docs are much easier to maintain in markdown than in rST.

Who is this for? I use markdown when I’m getting text from humans. *This* is just 10x easier than <i>this</i>, because I’m typing on my phone.

I love RestructuredText. My blog used to be on RST, because I hate markdown. I moved to Hugo and Markdown because I wanted to put out content, not fight the weird system that was Sphinx (My RST blog was running on it), and ablog, the Sphinx blogging framework didn't work with Furo, my favourite theme. I just use Hugo, and I use Claude to fix the css.

I use markdown because it's easy to read without rendering. All of the alternatives in the article seem worse

If I wanted more structure, I'd just write html; or mix html into the markdown.

Pandoc lets me do things like generate libreoffice or microsoft word documents from the markdown, using a reference document for styling of headings etc. This also gives me good enough control to generate OK looking pdfs. It's not LaTeX levels of control, but it's much easier

I don't want to do extra work to hypothetically make things easier for an LLM.

Even worse: social media postings. There are no semantics at all. People use emojis and so to structure the plain text

So I designed TapirMD [1], a new markup language which is still readable but more powerful, to help me (a tech writer) create web content.

[1]: https://tmd.tapirgames.com

It really is terrible. I've hated it ever since it was introduced, but it "won" before anyone ever adopted it, because there were webprogramming Apple/DaringFireball fanatics that pushed it everywhere they possibly could, and demanded that you acknowledge it as an ideal outcome.

The Apple/DaringFireball fanatics have gone, and the web programmers learned how to really program because they had node as an option, but we've been stuck with this ugly, limited non-standardized format.

I'm an AsciiDoc partisan. I think we should just standardize a subset of AsciiDoc that does everything that markdown does and let people just implement that subset if they want. AsciiDoc gets a bit hairy when you get into the weeds, but if there were some sort of graduated standard that layered on features, you could learn as slowly as you wanted, and only by necessity. AsciiDoc gives you what you need as a base to automate typesetting basically everthing, as far as semantics go.

edit: I have to admit that I do not like AsciiDoctor, but it's just because I hate introducing Ruby dependencies. The people behind AsciiDoctor seem really great.

Markdown is meant for less technically skilled users and cases where you just want to type something with a bit of structure and not bother with full html. Making universal claims of it being bad ignores the proper user cases for it. Author can write HTML as much as he wants, but don't tell the world that MD is bad.

Markdown is easy to get started with, that's the main selling point.

It's often the choice between Markdown or no documentation at all.

I love this post. While I don't mind markdown for quick notes which require basic formatting (headlines, bold, maybe a link), time and time again, I've found myself having to build parsing libraries and scripts for specific use cases just so the content can be interpreted correctly.

Take for example my blog, which I've had since 2016. It has been rebuilt into various systems over time and every time I had to migrate, there was a manual step of going over all posts and making sure they're displayed and interpreted correctly. In my last and current iteration, I've designed the system so that content is also stored with some hierarchical information (from html) like <section>, <article>, <address> etc, only applying styling to it when rendered.

I don't think we should stop using Markdown, but when something requires more than 200 lines of introductory text, more semantically enabled source feels necessary.

> Your content isn't just for human readers. Machines use it too. Your content gets indexed by search engines, and parsed by LLMs, and those things parse the well-formed HTML your systems publish.

Sounds like I need to start using Markdown!

My biggest problem with Markdown is that I hate writing in it. I find messing around with the syntax interrupts my flow.

Are others writing raw markdown/mdx or is there a CMS/Vscode plugin I should be using? (I have a few plugins already but find the writing experience pretty rubbish still)

I'm working on a HTML replacement right now. If I am to believe the author, it would solve her issue (I don't think so). But I don't know if I want to "share". Can I patent it? Good luck with that.

Going off-topic now, sort of.

The Open Source I see just isn't serious. We lose the right to have an opinion about a technology, to steer it, as that right is mediated by money, and it just evaporates, unless you can set the norm by being a major user, like a tech titan.

Markdown is special because we as developers are the users! Though tech titans dictate what we shall use. As developers we are seemingly in a concentration camp where others set the rules, and there is no escape, unless we surrender our work in the name of love, in the presence of those who absolutely don't, government included, and whose basic mode of operation is to make the profit on our work. It's just legalized demoralization, if not outright stealing.

If you're from a developing country you know what I'm talking about. There is no way to be creative and get paid. You are a beggar, no matter your talents. The end result is that human creativity remains untapped. That is the price we as a community pay every day. Heil the rise of AI, so we don't need each other any longer, and the abuse can stop ;-

There's crimes everyday, and we normalize them, if they are done by the trusted and verified, that talk about merit while they hire f*cks to do their bidding. As a community we are a harem, and they come to rape us, err, give us pleasure, whenever they feel like it, and expect us to love it. Well, don't you love your new toys? That is who we are. And we therefore tend to repeat the cycle in our homes, as "men".

In the end the framing as a technical issue is what marks us. It's is the safe zone, where we can deny the real issue, and cope. If you're a member of Nation Procrasti-me, you know what I'm talking about. Nation Procrasti-Me, Where Life Is Denied. And rent-seeking is the truth.

F*ck, how did we get so cooked? We shackled ourselves, duh. We are infants, or else outright dumb, dumb enough to give away our life force, for new toys to play. Worse, we dictate others do so too. That's when we stand on the side of the abuse, confidently like a toddler that just spread his shit all over the place and radiates "how good was that!".

Reading all these debates about document structure and formatting and so on is so wearying. I predict as long as we have text written by people the debates will continue. Truly a case of the taste of the writers and producers being a key variable that no one system will uniformly satisfy.