Should AI Output Be Markdown or HTML? Notes on the Claude Code Debate

Back in May, a short post from Thariq Shihipar on Anthropic’s Claude Code team split the dev community pretty cleanly down the middle. It was called “Using Claude Code: The Unreasonable Effectiveness of HTML,” and it spread fast — fast enough that Simon Willison, who’d defaulted to Markdown for years, publicly admitted he was reconsidering.

The pitch is blunt: stop asking the model for Markdown and start asking it for HTML.

Before getting into who’s right, there’s one distinction that matters, because a lot of the secondhand coverage got it wrong. The claim is not “rewrite your spec files in HTML.” It’s about the format you ask the model to produce when it’s showing you something — a plan, a review, a report. Nobody is telling you to turn CLAUDE.md into an HTML file. Keep that straight and the rest of the argument makes a lot more sense.

The case for HTML

What’s interesting is that the argument doesn’t start with technology. It starts with a change in behavior. Thariq points out that he barely edits these files by hand anymore. They’ve become specs and reference material, and when something needs changing, he just asks Claude to change it. The moment that’s true, Markdown loses the one thing it was best at — being easy for a human to edit — and you’re left holding only its limitations.

On top of that, he makes four points.

Density of information. HTML handles basic document structure fine, but it also does tables, CSS, SVG illustrations, code blocks, interactive bits with JavaScript, images — close to anything the model wants to express. Markdown, by contrast, ends up faking it: approximating colors with Unicode characters, drawing diagrams in ASCII. Worth being precise here, though: the “density” we’re talking about is what a person can take in on screen at a glance, not token efficiency. On tokens, Markdown actually wins, and we’ll get back to that.

Readability at scale. Thariq’s honest about this one — he doesn’t really read a Markdown file past about a hundred lines, and he definitely can’t get anyone else on his team to. As the model writes longer and more detailed plans, that ceiling becomes a real problem. HTML lets you break things into tabs, add diagrams and links, even make it responsive, so the document actually gets read instead of skimmed and abandoned.

Sharing. Markdown renders nicely inside GitHub or whatever doc tool you’re in, but if you want to hand someone a single file they can open in a browser, you need a rendering step somewhere. An HTML file you can just upload and send the link. The odds of a colleague actually opening your spec or PR writeup go up.

Two-way interaction. This is where it gets genuinely different from a document. You can have the model add sliders or knobs to tweak a design or an algorithm’s parameters, see what changes, then copy the result back into a prompt. Things that are a pain to describe in text — a color, an easing curve, a crop region, a cron schedule — you nudge in the UI and pull back out with a “copy as JSON” button.

His real motivation, though, is the part I find most honest. As Claude took on more, he caught himself reading plans less carefully and just handing them off. He wanted to stay in the loop. HTML turned out to be the thing that pulled him back in. Framed that way, this isn’t really a fight about file formats — it’s about keeping a human involved in the decisions the model is making.

When people bring up the token cost, his answer is straightforward: yes, Markdown is cheaper, but the richer output and the higher chance he’ll actually read it make for a better result, and with a million-token context window the extra tokens don’t really register.

The case for sticking with Markdown

The pushback was just as loud, and most of it lands in four areas.

Version control. This is the one that comes up most. Markdown and YAML were built to live in a repo — to be diffed, reviewed, and shipped through a PR. HTML diffs get noisy, and the gap between the rendered page and the source makes review awkward. A document that looks good and a source file your team can actually collaborate on are two different things.

Security. Static HTML and CSS, the risk is limited. But the moment AI-generated JavaScript is in the mix, it changes. Buttons, file handling, outbound requests, copy functions — once any of that shows up, you need review and sandboxing, and trusting code the model wrote and opening it in your browser is its own attack surface. Bigger payloads and sanitization overhead come along for the ride.

Token cost. Everything Markdown is good at — portability, low token use, clean diffs — is more or less where HTML is weak. A fair number of writeups landed on calling this a tradeoff between information design and token efficiency rather than a settled answer, and that’s about right.

Don’t oversell it. One critic made the case that Markdown isn’t just a lightweight text format — it’s the substrate of knowledge work, with readable source, security, ecosystem support, and reviewability all baked in. Trading that for visual polish, the argument goes, is a step backward in real work. And it’s worth remembering Willison didn’t throw Markdown out; he said he’d reconsider it for output. “Pick the right tool for the job,” not “replace everything,” was where most level-headed people ended up.

So when do you reach for which?

It sounds complicated, but the call comes down to one question:

Is this something you’ll commit to the repo, version, and edit by hand — or something you’ll look at once, review, and throw away?

First one, Markdown. Second one, HTML. Here’s the same idea as a table.

	Markdown	HTML
Token efficiency	High	Low
Git / PR / diff / review	Strong	Weak
Expressiveness / visuals	Limited	Rich (SVG / CSS / JS)
Readability past 100 lines	Drops off	Good
Sharing	Needs a renderer	Open in any browser
Editing by hand	Easy	Hard
Security overhead	Basically none	JS / sanitization to weigh
Nature	Durable source	Throwaway artifact

Where Markdown is the right answer: CLAUDE.md, DESIGN.md, ADRs, the layered config files in a monorepo — anything that lives in the repo and goes through a PR. This is exactly the territory where the skeptics’ arguments hold. Version control and reviewability beat polish every time.

Where HTML earns its place: annotated diffs for a PR review, laying out several UI directions side by side, walking through a gnarly data flow or architecture, a one-off report or explainer you read once and you’re done. The “show a human something for review” cases.

You don’t need to make a big deal of getting started, either. Thariq’s own advice is to just tack “make an HTML file” or “make an HTML artifact” onto your prompt. If a pattern keeps coming up, that’s when you turn it into a skill.

Wrapping up

The real lesson here isn’t “Markdown is dead.” It’s that the nature of what AI produces is shifting. It used to be documents a human wrote and a human edited. Now it’s increasingly stuff the model writes, a human reviews, and the model picks back up. In that world, the question behind every format choice is really how do I stay in the loop?

There’s no reason to abandon Markdown. But the reflex of defaulting every output to it is worth questioning. Keep in the repo what’s Markdown; make HTML what you show and discard. That distinction gets you most of the way there.

To put a finer point on it, this was never really an either/or. The sane move is to treat HTML not as the source of truth but as a view derived from it. The durable decisions still live in Markdown, ADRs, YAML, and code; HTML is the temporary interface that helps a person understand and respond to them faster. As a flow:

Markdown / YAML / code comments / ADR   ← source of truth
            ↓
AI generates an HTML explainer or review artifact
            ↓
human reviews and gives feedback
            ↓
decisions go back into Markdown / code / issues   ← source of truth updated

The pretty HTML artifact is one box in the middle of that loop — not the place where the truth lives. Not confusing those two is the most practical thing to take away from the whole debate.

References

• Thariq Shihipar, “Using Claude Code: The Unreasonable Effectiveness of HTML” (Anthropic blog)
• Example gallery: github.com/anthropics/html-effectiveness / thariqs.github.io/html-effectiveness
• Simon Willison’s commentary (simonwillison.net)
• Counterpoint: “The Unreasonable Ineffectiveness of HTML” and other community critiques