HTML vs Markdown: The Format War Reshaping AI Work

A debate about file formats sounds, on its face, like the kind of thing that gets argued about in Discord servers at 2 a.m. and nowhere else. But a recent essay by Tariq Shahriar, an engineer on Anthropic's Claude Code team, has apparently been seen around 10 million times—which suggests something more interesting is hiding underneath the nerd terminology.

The essay, titled "The Unreasonable Effectiveness of HTML," makes a straightforward case: Markdown, the plain-text formatting language that has quietly become the lingua franca of AI agent workflows, is no longer up to the job. Shahriar argues it should be replaced—or at least supplemented—by HTML. His reasons are practical: information density, readability, shareability, and interactivity. HTML can render tables, diagrams, CSS-styled layouts, and SVG illustrations. A Markdown file mostly cannot. When you need to hand a 300-line specification document to an AI coding agent, the argument goes, the richer container wins.

Ten million views for a technical essay suggests this isn't really a debate about file formats. It's a debate about what's changing in how people work.

The Strongest Version of the Argument

To be fair to Shahriar's position—and fairness requires engaging with its best form—the argument isn't simply "HTML is better than Markdown." It's that the use case has changed, and the format hasn't kept up.

Markdown's original appeal was human editability. It's legible as plain text. You can write it in any text editor, push it to GitHub, render it almost anywhere. For years, that was sufficient. Developers used it for documentation. AI users started using it for context handoffs: dump the summary of your conversation with ChatGPT into a .md file, carry it into Claude Code, and continue the work. Simple, portable, functional.

But Shahriar's observation—and it's worth sitting with—is that he's not really editing these files anymore. As he wrote: "I'm also increasingly not editing these files myself, but using them as specs, reference files, brainstorming outputs, etc. When I do make edits, I'm usually prompting Claude to edit them, which removes one of Markdown's largest benefits."

That's the crux. Markdown's main virtue was human editability. If a human isn't editing it, the virtue evaporates. What remains is a format optimized for a workflow that's been superseded. Meanwhile, the files themselves are getting longer and more complex as agents take on more ambitious tasks. Shahriar notes, candidly, that he doesn't actually read Markdown files longer than 100 lines—and he definitely can't get colleagues to read them either.

HTML, he argues, can be structured to be navigable. It can have tabs, internal links, visual hierarchy. You can open it in any browser. You can share a link to it. You can embed interactive elements—sliders, toggles—that let a human adjust parameters and pipe the changes back into a prompt. In his framing, HTML becomes less a document format and more a staging environment: a place where a human and an agent can hand work back and forth in ways that feel more like collaboration and less like file management.

The concrete use case he describes is worth noting: start a new problem by asking an AI to generate a web of exploratory HTML files—different approaches, mockups, code snippets—then select the most promising direction, ask for an implementation plan, and pass all of those files to a fresh session for execution. The HTML isn't the output. It's the scaffolding.

Where the Skeptics Have a Point

The critique that immediately surfaced—and it's not cynical to raise it—is tokens. HTML is verbose. The same information that fits in a lean Markdown file can balloon significantly when wrapped in HTML tags, styled with CSS, and structured for browser rendering. More tokens means more cost, longer context windows, and potentially slower responses.

Josh Daw put the sharpest version of this plainly: "The cynic in me can't help but note that HTML will cost way more tokens than Markdown."

The cynical extension of that observation is that Shahriar works at Anthropic, and Anthropic's business model is selling tokens. More verbose formats help that business. The less cynical version—probably the more accurate one—is that he may genuinely believe what he's saying, but the incentive structure is worth naming anyway.

There's also a subtler issue. Shahriar's argument works best for a specific class of user: someone running heavy, multi-session agent workflows, producing complex specifications, and sharing outputs with other humans who need to actually read them. For that person, HTML's richness earns its token cost. But for someone using Claude to draft an email or summarize a meeting, the overhead is absurd. The format question doesn't have a universal answer—it has a situational one.

Some practitioners have validated the HTML approach in specific contexts. One developer, Jayun Ha, described switching mid-project while writing a technical explainer: "Started the codec/goal explainer in Markdown last night, and about halfway through I was like, why am I fighting this? Switched to HTML. The flow diagram alone made it worth it. I can't really go back to be honest." The key detail there: he was producing something intended for human consumption. The HTML wasn't just a machine-readable spec—it was a deliverable.

That distinction matters. When the artifact is headed toward a human reader, HTML's rendering advantages are real. When it's purely machine-to-machine context transfer, the case is weaker.

The Bigger Shift Underneath the Format Debate

What makes this conversation stick isn't really the Markdown-vs-HTML question. It's what that question reveals about how AI workflows are evolving.

The old model: you talk to an AI, the AI produces something, you edit it, done. The emerging model: you set up a problem, hand an agent a rich context package, the agent executes across multiple steps, you review outputs, and you iterate. The human role moves from producer to director—or maybe to curator and quality-control.

In that second model, the format of context transfer becomes load-bearing infrastructure. If the spec is ambiguous or hard to navigate, the agent's output degrades. If the output is hard for a human to review, errors compound. The file format isn't a detail; it's a design decision that shapes the quality of everything downstream.

This is, at minimum, worth taking seriously as AI coding tools become more capable and more people start delegating not just tasks but entire project phases to agents. The question of how you hand off work—with what richness, in what structure, with what interactive affordances—is becoming a real skill.

Whether HTML specifically is the right answer, or whether something else eventually emerges (structured JSON? purpose-built agent specification formats?), is still genuinely open. The practices are young enough that anyone claiming definitive answers is probably overselling their certainty.

What seems clearer is that the people treating these format questions as trivial are probably the ones who haven't yet tried to review a 400-line Markdown spec that their agent produced at 11 p.m. and needs to be correct by morning.

---

By Marcus Chen-Ramirez, Senior Technology Correspondent