In May 2026, Thariq Shihipar — engineering lead for Claude Code at Anthropic — posted nine words on X that broke the internet’s formatting consensus: “HTML is the new markdown.”

The companion article, “The Unreasonable Effectiveness of HTML,” racked up millions of views in under 24 hours. Simon Willison publicly reconsidered his three-year markdown default. Hacker News erupted. And suddenly, the most boring topic in tech — output file formats — became the most interesting debate of the year.

Here’s the thing: both sides are right. They’re just talking about different problems.

The case Thariq actually made

Thariq’s argument wasn’t about input. It was about what AI agents produce for humans to consume.

His team ran 20 prompts through Claude Code, producing both markdown and HTML output. HTML won 17 of 20 head-to-head comparisons. The three it lost were tasks where the output stayed internal to the agent’s loop — stuff no human would read anyway.

The reason is structural. Markdown was designed for readable plaintext. It does headers, bold, links, and code blocks well. But the moment you need color-coded diffs, tabbed navigation, inline SVGs, or a compact mini-dashboard, you’re fighting the format. HTML handles all of that natively.

When models had tiny context windows and every token counted, markdown’s efficiency was a killer feature. With context windows now stretching past a million tokens, that constraint has loosened. If you’re asking an agent to generate a code review, a project plan, or a design system spec — something you’ll open in a browser and actually use — HTML is the better output format. Period.

The case for markdown (and it’s a strong one)

But here’s what the “HTML is the new markdown” crowd glosses over: the web’s fastest-growing content consumers aren’t humans. They’re AI agents. And agents don’t want your styled divs and JavaScript bundles.

In February 2026, Cloudflare launched Markdown for Agents — a feature that converts HTML to markdown at the edge when an AI system requests it. The mechanism is elegant: same URL, same content, but the server checks the HTTP Accept header. A browser sends Accept: text/html and gets the full page. An AI agent sends Accept: text/markdown and gets clean, structured text.

The numbers are striking. Cloudflare’s benchmarks showed a typical blog post dropping from 16,180 HTML tokens to 3,150 markdown tokens — an 80% reduction. For e-commerce product pages, the savings hit 95%. That’s not a rounding error. That’s the difference between an agent that can process your entire documentation site in one pass and one that burns through its context window on three pages.

Vercel followed with the same pattern for their blog and changelog. Checkly independently confirmed the numbers on their own docs. And this isn’t some experimental hack — content negotiation via the Accept header has been a core HTTP feature since RFC 2616 in 1999. The standard was sitting there for 27 years, waiting for a use case.

It’s not either/or — it’s about the layer

This is where I land on it personally: the debate isn’t markdown versus HTML. It’s about understanding which layer each format serves.

Markdown is for authoring and agent consumption. I write everything in Obsidian — notes, drafts, project docs. Markdown is fast, portable, Git-friendly, and human-readable in its raw form. When an AI agent needs to consume content from the web, markdown is objectively better: fewer tokens, cleaner structure, no layout noise.

HTML is for human presentation. When I need to share information with a group of people — a polished presentation, an interactive report, a client-facing deliverable — HTML is unmatched. You get full control over layout, typography, color, and interactivity. You can embed charts, create tabbed views, build responsive layouts. It’s a presentation layer, and it’s excellent at that job.

The smart approach in 2026 isn’t picking a side. It’s writing in markdown and serving both formats depending on who’s consuming it.

What this means for your stack

If you run a content site today and you’re not thinking about how AI agents consume your pages, you’re leaving value on the table. Agents are becoming real traffic — they fetch your documentation, your pricing pages, your blog posts. Serving them 16,000 tokens of HTML when 3,000 tokens of markdown would do is wasteful for everyone.

The practical takeaway:

  • Content creators: Write in markdown. Use tools like Obsidian, HackMD, or any markdown editor that fits your workflow. Your content stays portable and agent-ready.
  • Site operators: Look into content negotiation. If you’re on Cloudflare, Markdown for Agents is available in beta on paid plans. If not, the pattern is implementable on Vercel, Netlify, or any server that supports HTTP headers.
  • Developers: Build for both audiences. Your human visitors get the rich HTML experience. AI agents get the lean markdown version. One URL, two formats, zero compromise.

And here’s a teaser: there’s a way to go from an idea on your phone to a polished, shareable web page deployed on Cloudflare Pages in minutes — for essentially zero cost. A lightweight pipeline that takes markdown content, wraps it in a clean HTML presentation layer, and publishes it automatically. I’ll be writing about that stack soon.

References

  • Thariq Shihipar, “Using Claude Code: The Unreasonable Effectiveness of HTML” (May 2026) — X/Twitter
  • Cloudflare, “Introducing Markdown for Agents” (Feb 2026) — Cloudflare Changelog
  • Checkly, “The Current State of Content Negotiation for AI Agents” (Feb 2026) — Checkly Blog
  • Ernie Smith, “The Great Markdown Rebranding of 2026” — Tedium
  • HackMD, “Built for Agents: Markdown-Native Content Negotiation” (Mar 2026) — HackMD Blog