HTML Is the New Markdown: What It Means

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.

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:

• Curious how AI workflows change day-to-day work? Read: AI Workflow for Solo Founders: What Actually Works

• If output is becoming a workspace instead of a chat, read: AI Workspace Agents: What Changes Beyond Chat Interfaces

• 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

• Thinking about keeping work artifacts inside one environment? Read: Stop Context Switching: Why Workspace Agents Matter