Markdown won a long time ago, and it deserved to. It is plain text, so it survives anything. It is readable before it is rendered. You can write it in any editor, diff it in git, paste it into an email, and it still makes sense. For two decades it has been the path of least resistance for a person with a keyboard and something to say.
But notice the shape of every reason it won. Each one is a story about a human typing.
Asterisks for emphasis are fast to type. Pound signs for headings are fast to type. The whole grammar is a set of shortcuts a person can reach without lifting their hands or thinking about markup. Markdown is, at heart, a typing format. It optimized the one step that used to be expensive: getting structured text out of a human and onto the page with the least friction.
That constraint is quietly going away. Not because Markdown got worse, but because the person who used to do the typing increasingly does not.
Why agents write Markdown
When you author a document by hand, the format you reach for is the one that fights you least. Rich layout is possible, but it costs attention. Every table you draw, every column you align, every callout you style is time spent on presentation instead of thinking. So people learned to keep it simple. A long Markdown document is what you get when a smart person is in a hurry and the structure has to come out of the same hands that are doing the reasoning.
This is why so much agent output today looks the way it does. The agent writes Markdown because that is what it learned from, and what it learned from was written by people optimizing for typing speed. The default carried over. We inherited a constraint we no longer have.
Think about what that constraint actually bought us. It bought a format where a comparison is three paragraphs that you hold in your head, because drawing the table by hand was not worth it. It bought headings as the main structural tool, because anything richer was a chore. It bought the wall of prose, lightly punctuated by bullets, that is the native shape of fast human writing.
None of that is a law of good documents. It is a fossil of how documents used to get made.
The same brief, twice
Take the worked example that runs through these essays: an agent does a small customer research project, four interview transcripts in, one synthesis out. The synthesis is the artifact you care about, the thing you will reread before a build decision.
In Markdown, that synthesis is complete, accurate, and roughly a hundred and twenty lines. The middle of it looks like this:
Finding 2: Speed beats depth
Three of the four interviews surfaced the same constraint:
the recap is only useful if it arrives before the next
meeting starts. Nobody asked for more depth.
"Five bullets. In Slack. By the time I'm out of the building."
Multiply that by three findings, add a method heading on top and a numbered recommendation list at the bottom, and you have the document. To know whether the four interviews agreed, you read top to bottom and assemble the pattern in your own head. To find the recommendation you scroll. To weigh a quote against the finding it supports, you hold both in memory because they are forty lines apart. It is all there. It is just laid out for the writer, not the reader.
Now the same synthesis as an HTML page. Same words, mostly. But the three findings are not a list you scroll through, they are three labeled blocks you take in at a glance: "Length is the enemy," "Speed beats depth," "Land it in the work tool." The supporting quote sits inside the finding it supports, set apart, so the evidence is next to the claim instead of below it. Who was interviewed is a short table with role and company, so you can see the spread of perspectives without parsing a sentence. The recommendation is its own panel at the end, three numbered steps, visually distinct from the analysis that earned it.
Nothing was decorated. Same words, same findings, same quotes. But you can answer "did they agree, and what should we do" in fifteen seconds instead of two minutes of scrolling and reassembly. The gain is cognitive ergonomics: the layout doing some of the reader's work for them.Structure is an argument
The interesting thing about that second version is that the structure is not neutral. A table says these four perspectives are comparable along these axes. A quote pinned beside a claim says this is the evidence, judge it here. Three equal blocks say these findings carry equal weight; a numbered list says this one comes first. The layout is making claims about how the content relates to itself.
When a human types, they mostly cannot afford to make those claims in the layout, so they make them in prose: "more importantly," "in contrast," "the strongest signal was." The structure lives in the sentences. That works, but it asks the reader to rebuild the shape from the words every single time.
An agent does not have hands, and does not get tired drawing a table. The cost that made humans flatten everything into prose is gone. So the agent can put the structure where it belongs, in the structure, and let the reader spend their attention on judgment instead of reconstruction. This is the part worth sitting with: richness stopped being expensive at exactly the moment the author stopped being a person.
HTML as compiled thought
The reflex is to think of HTML as a website format. Pages, links, navigation, the open web. That framing is too small for what is happening here. HTML is also, simply, the most capable reading format we have that is still just a file. It can hold a heading and a table and a quote and a small chart in one document, render the same on any screen, and open in anything for the next twenty years without a special app.
So it helps to stop calling it a website format and start calling it an artifact format. The agent does the messy work in conversation, the back and forth, the false starts, the corrections. The HTML page is what that work compiles down to: a clean, inspectable, structured object you can open and trust. Compiled thought. The reasoning happened elsewhere; this is the result, laid out so a human can verify it quickly.
You can see the two formats living side by side in Caipi's public demo workspace: the knowledge-base notes are plain Markdown, while the front page and the expenses dashboard are laid-out HTML, each right for what it is. And once an artifact is an HTML file, giving it a real URL is a small step; here is how to do that with a Claude artifact.
Markdown can be that too, for many things. A short note, a changelog, a snippet of code, a quick reply: Markdown is exactly right there, and reaching for a full HTML page would be silly. I am not campaigning against Markdown. It is plain text, it is portable, it will outlive most of what we build on top of it, and I made the longer case for boring formats in Files You Can Still Open After You Cancel. My claim is more specific: Markdown's dominance over substantial documents rested on a human constraint, and where that constraint is lifting, the default should be allowed to lift with it.
Let the reader set the format
None of this reduces to "HTML good, Markdown bad." The point is that we have been letting the author's tooling pick the format, and the author used to be a person typing fast, so the format optimized for typing fast. Now the author is often an agent that can produce any structure at no extra cost, and the human's whole job has moved to reading and deciding. The format should follow the work, and the work is now mostly read.
That is the small, real shift. When the writing was the bottleneck, the format served the writer. Now that the reading and the judgment are the bottleneck, the format should serve the reader. A synthesis the agent writes once and you reread before a decision should arrive as a page you can take in, not as a hundred and twenty lines of scroll.
This is only the static case, the document you read. There is a further step, where the page stops being something you read and starts being something you use, a view over live data that answers back; I make that argument in The Leap From Documents to Tools. The modest claim stands on its own: when nobody has to type it, a document can finally be shaped for the person who has to understand it.