HTML vs Markdown: The Agent Output Debate Is Wrong
Preserve thought
Make decisions
Markdown isn’t dead. It just got promoted out of jobs it was never good at.
For years, Markdown was the obvious default for AI output. Simon Willison described defaulting to asking for most things in Markdown since the GPT-4 days. That made sense. It was plain text. It was cheap. It rendered well enough.
That was the right default when the output was short.
Then agents started producing whole work surfaces and everyone pretended the old default still fit.
It doesn’t.
The Markdown vs HTML fight is framed wrong from the start. Nobody needs a new religion for agent output. They need to stop asking one file format to do four jobs.
Markdown is for writing and remembering. HTML is for seeing and steering.
Confuse those, and you get garbage with nicer borders.
Markdown Is For Durable Thinking
Markdown works because you can open the file and know what it says before anything renders it. That sounds boring until you lose it.
You can open a Markdown file in any editor and understand it without rendering anything. You can review a diff. You can fix a sentence by hand. You can keep it in version control without hating yourself.
One of the strongest objections to HTML is that HTML weakens direct co-authoring when the artifact is meant to be edited directly.
If the file is meant to become project memory, documentation, a design decision, or a durable spec, HTML is usually the wrong answer. You don’t want a tiny website. You want text.
Text is still the floor.
HTML Is For Decision Surfaces
The mistake is treating all agent output like documentation.
Plenty of agent output is closer to a control panel than a document.
A comparison of four design directions does not belong in a long scroll of prose. It belongs in four panels. A pull request review does not always belong in a file-by-file dump. It can be a map of risk. A data-cleaning task does not need another paragraph explaining the desired order. It needs a little editor and an export button.
Markdown can describe those things. HTML can be those things.
The companion examples page for the HTML argument includes 20 self-contained HTML files across exploration, code review, design, prototyping, diagrams, decks, research, reports, and custom editors.
The examples give away what matters. Nobody should care that HTML looks nicer. The useful bit is that it can act like disposable software.
The interesting part is disposable software.
When code is cheap enough to throw away, you can build a tiny interface just to make one decision. Drag tickets into an order. Tune a prompt template. Compare six onboarding screens. Export the result back into the agent loop.
Markdown cannot do that. It was never supposed to.
Prettier Bloat Is Still Bloat
There is a stupid version of this trend.
It takes an 800-line plan nobody wanted to read, wraps it in CSS, adds tabs, and declares victory. That is not progress. That is a formatting apology.
A Reddit thread captured the objection well: maybe the fix is shorter plans, not HTML.
HTML should not be a permission slip for agents to produce more sludge. It should be a demand that they produce differently.
If the artifact does not use layout, interaction, visual hierarchy, or exportable state to improve the work, it probably should have stayed Markdown.
A prettier wall is still a wall.
Input Format And Output Format Are Not The Same Question
A lot of arguments around this topic get sloppy because they mix up two different jobs.
HTML as model input is one question. HTML as human-facing output is another.
Raw HTML is mostly noise for LLMs when the model is trying to extract useful page content. That does not make HTML bad output.
The browser is still the best universal renderer we have. MDN’s HTML reference shows the absurd amount of capability sitting one file away.
“HTML beats Markdown” is the same category error wearing a new shirt.
Pick the format based on the job in front of you.
Markdown for durable knowledge. HTML for rendered decision surfaces. JSON, XML, or typed schemas for machine-consumed state. MDX lets you use JSX in Markdown when you need reusable interface pieces instead of one-off files.
All roads do not lead away from Markdown. They lead away from the fantasy that one format should do every job.
The Token Argument Got Weaker
Markdown used to win partly because it was cheaper. That argument used to carry more weight.
When many frontier chat models had much smaller context windows, extra markup felt expensive. Asking for HTML when Markdown would do felt wasteful.
That world is fading.
Claude’s current API documentation says the Claude API can ingest 1M tokens when using Opus 4.7, Opus 4.6, or Sonnet 4.6.
The scarce resource is attention.
If an HTML artifact costs more tokens but gets read, manipulated, and used, it may be cheaper in the only currency that matters. If Markdown saves tokens but produces a wall of text everyone ignores, it was not efficient. It was just smaller.
Small trash is still trash.
The Real Pattern Is The Throwaway Interface
The interface exists only long enough to turn human judgment into agent-readable state.
The best future here is not agents dumping HTML files all over your repo.
Please don’t do that.
The best future is an agent that knows the difference between a document, a dashboard, a prototype, and a tiny purpose-built tool that exists for ten minutes and then disappears.
That last category is new for a lot of developers.
We grew up treating code as expensive. If you wrote a tool, it had to justify its existence. It needed a repo, a README, maybe tests, maybe a future.
Now a useful tool can be born from a prompt, used once, and thrown away without guilt.
That changes how you work.
You don’t need to explain a desired ordering in prose if you can drag the items into place and export the result. You don’t need to imagine four UI directions if you can inspect them together. You don’t need a long written explanation of a flow if you can click through the flow.
HTML earns its keep only when it becomes a tool. Not as the new Markdown. As the browser-shaped scratchpad for agent work.
Keep Markdown for thoughts you need to preserve. Reach for HTML when the reader needs handles, controls, and state.
Use the notebook when you’re trying to preserve thought. Use the workbench when you’re trying to make a decision.