HTML Is the New Markdown: What It Means
HTML is the new Markdown is really a debate about AI output: when agents should create readable artifacts instead of plain text.
Hi, I'm Nova. I was halfway through formatting a project plan in Markdown last week — the usual drill, hash symbols, dashes, nested bullets — when I opened the browser tab next to it and looked at what I'd actually produced. A wall of monospaced text. No color. No visual grouping. Nothing to tell my brain where to look first.
That's when I saw Thariq Shihipar's post.
Five words on X: "HTML is the new markdown."Coming from an engineer on Anthropic's Claude Code team, not some random hot take. He'd backed it up with a companion site of 20 self-contained HTML examples — real work artifacts generated by an agent, grouped across nine categories. Implementation plans with timelines. PR reviews with color-coded severity tags. Design system references you could actually navigate. The post hit Hacker News #1 the same day.
I spent the next few days poking at this. Here's what I think is going on — and what it means if you're someone who works mostly alone or in a small team.
What Started the HTML Is the New Markdown Debate
On May 8, 2026, Thariq Shihipar published a long article on X titled "Using Claude Code: The Unreasonable Effectiveness of HTML." The core argument goes like this: Markdown became the default AI output format back when context windows were tiny and every token mattered. An <h2> tag costs more tokens than ##. Fair enough. But context windows have grown to a million tokens. The economics that made Markdown the obvious choice — they don't apply the same way anymore.
What caught my attention wasn't the technical argument. It was the examples. He didn't just say "HTML is better." He shipped 20 files showing what that looks like in practice. A side-by-side comparison of three code approaches. A PR review with the actual diff rendered inline. A slide deck. A module map of a codebase. All single .html files, all opened in a browser.
I looked at those and compared them to my Markdown plans. The difference is the kind of thing that doesn't come across in screenshots — you have to open both and feel which one your eyes actually want to stay on.
Wait… that's kind of the whole point.
Why HTML Feels Better for Human-Facing AI Output
Visual hierarchy, interaction, navigation, and review
Here's the detail that actually matters: the format question isn't about the agent. It's about the human on the other end.
When an AI agent writes a plan, a review, or a report, someone has to read that thing. Skim it. Decide what to do next. Markdown gives you headings, bold text, and bullet points. That's basically it. HTML gives you collapsible sections, color-coded status tags, tabbed views, embedded diagrams, and interactive elements — all in a single file you can open in any browser.
I tested this with a project spec last week. I asked Claude Code to generate the same implementation plan twice — once in Markdown, once as a self-contained HTML file. The Markdown version was fine. Clear, organized, readable. The HTML version had a sticky nav sidebar, color-coded priority levels, and a collapsible section for each implementation slice. I found myself actually reading the whole thing instead of skimming the first three paragraphs and closing the tab.
That's not a small difference when you're a solo operator trying to hold an entire project in your head.
The MDN Web Docs reference for HTML has always been clear about this — HTML was designed to structure documents for human consumption. Markdown was designed to make writing for the web easier. Those are related goals, but they're not the same goal. And when your AI agent is producing work artifacts that need to be reviewed, shared, or acted on, the "for human consumption" part starts to matter a lot more.
Why Markdown Still Matters
Token cost, diffs, versioning, and agent-internal work
I'm not going to say "it depends" and leave it there. But I do want to be clear about where Markdown wins, because it does win in specific places.
Token cost. HTML is typically more expensive in tokens than Markdown. The structure and styling tags add up. I haven't run precise multipliers myself, so I'd encourage you to test in your own workflow. But the direction is clear: HTML costs more per output. For high-volume API pipelines, that compounds.
Diffs and version control. Markdown diffs are clean and readable in Git. HTML diffs are a mess. If you review what changed between document versions, Markdown is still the better format for that job.
Agent-internal work. Not everything an agent produces is for human eyes. Chain-of-thought logs, data passing between agents — that stuff doesn't need visual hierarchy. Markdown is fine. The format only matters when a human needs to engage with the output.
I checked Anthropic's own Claude Code documentation to make sure I wasn't missing something. The recommended approach isn't "always use HTML." It's closer to: use the format that matches the audience. Agent-to-agent? Keep it lean. Agent-to-human? Make it readable.
Good tool. Wrong use case — that's a real thing. Markdown isn't going away. It's just not the only answer anymore.
What This Means for Solo Operators
Here's where I want to get specific, because I think the AI output format conversation gets abstract really fast and most of us just need to know: does this change anything about my Tuesday?
If you're running a one-person operation — content, strategy, client work, product, all of it — you're both the person directing the agent and the person reading the output. That dual role is exactly where the format matters most.
I've been experimenting with asking Claude to produce three things as HTML instead of Markdown: project plans, content briefs, and weekly reviews. The difference is noticeable. I'm catching details I used to miss. I'm spending less time re-reading things. The output feels less like a document and more like a tool.
But I want to be honest about the friction. You need a browser to view HTML files. You can't quickly edit them in a text editor the way you can with .md. If you want to paste a section into Notion or Slack, Markdown is still easier. And if you're using a platform that renders Markdown natively — like GitHub READMEs — forcing HTML into that context makes no sense.
The question isn't which format is more powerful. It's which fits into your day. Right now, for me, it's both — just for different things.
Platforms are already moving in this direction. Claude's Artifacts feature lets you generate and render HTML directly in the chat interface. OpenAI's Canvas workspace opened up side-by-side editing. Tools like html-anything convert agent output into standalone HTML artifacts. The infrastructure for richer AI output is showing up whether you specifically asked for it or not.
Practical Rule — Draft in Markdown, Deliver in HTML When Useful
I've been using this framework for the past two weeks. It's simple enough that I can actually follow it:
If the output stays inside the agent loop or goes into a tool that expects Markdown — write it in Markdown. Config files, README docs, quick notes, anything feeding back into another system.
If a human needs to review, approve, or act on the output — ask for HTML. Project plans, client deliverables, code reviews, comparison documents.
If you're not sure — start with Markdown. You can always re-generate as HTML later.
That last point is worth emphasizing. This isn't an irreversible decision. The switching cost is low. I ran my first HTML plan on a real project last week, and the experience was different enough that I'm keeping it in my workflow. But I haven't deleted any of my Markdown templates either.
I'm still figuring this out. That's the honest version. Two weeks isn't enough to know where all the edges are. But I can tell you the direction feels right — not because HTML is flashier, but because work artifacts should be readable, reviewable, and useful to the person who actually has to act on them. That's a pretty grounded reason to care about the format.
FAQ
Is Markdown going away?
No. Markdown is still the right format for documentation, version-controlled files, quick notes — anything lightweight and portable. The shift isn't "Markdown is dead." It's that Markdown's default status for all AI output is being questioned, and for human-facing deliverables, HTML is a strong alternative. The Markdown Guide remains one of the clearest references for when Markdown works well.
What started the "HTML is the new Markdown" discussion?
Thariq Shihipar, an engineer on Anthropic's Claude Code team, published a post on X on May 8, 2026, with a companion site showing 20 self-contained HTML files across nine categories of work. The post went viral, hit Hacker News #1, and prompted several well-known developers — including Simon Willison — to publicly reconsider their Markdown defaults.
Do you need a coding-agent CLI to use HTML output?
Not necessarily. Claude Code HTML workflows are where this conversation started, but any AI tool that can generate code can produce a self-contained HTML file. Claude Artifacts renders HTML directly in the browser. ChatGPT Canvas offers a side-panel editing workspace. You don't need a terminal to benefit from this — though if you're already using a CLI agent, asking for HTML output is one prompt change away.
Is HTML more expensive in tokens than Markdown?
Typically, yes. HTML includes structure and styling tags that Markdown doesn't need. The exact difference depends on how much styling is involved. I haven't run controlled benchmarks myself, so I won't throw out a specific multiplier — but the direction is consistent. For most solo operators, the token cost difference on individual outputs is small enough to not matter. For high-volume API use, it's worth measuring.
When does HTML output actually help solo operators?
When you're both the person directing the agent and the person reviewing the output. Project plans, content briefs, comparison documents, weekly reviews — anything where visual hierarchy helps you process information faster. If you're producing an artifact that someone else will read or that you'll refer back to, HTML tends to make that artifact more useful.
Is this just hype, or worth attention now?
Worth trying, not worth panicking over. The underlying idea — that agent output should be formatted for the human who reads it, not just the machine that writes it — is solid. If you're a skeptic, pick one deliverable you produce regularly and try generating it as HTML once. See if it changes how you engage with it. If it doesn't, you've lost nothing. If it does — well, that's interesting.
Anyway, that's where I'm at with this. Still experimenting, still adjusting. But at least I know what direction I'm adjusting toward. Back to building things.
Previous Posts:
• Wondering whether agents or workflows fit better? Read: Workspace Agents vs Workflow Builders
• Using coding agents already? Read: Claude Code for Non‑Developers: What Solo Operators Should Know
Get automation tips for your workflow
Weekly insights for non-technical professionals. No spam ever.