Claude Code: HTML Beats Markdown

Table of Contents

TL;DR: HTML vs Markdown in Claude Code

What happened: On May 8, 2026, Anthropic engineer Thariq Shihipar (Claude Code lead) published “The Unreasonable Effectiveness of HTML” arguing that HTML, not Markdown, is the better output format for AI agents in 2026.
The viral arc: 4.4 million views in 16 hours. 8 million in under a day. Anthropic itself now uses HTML as the internal default for plans, code reviews, design systems, and reports.
The argument in one line: Markdown won the AI-output war when context windows were small and every token mattered. Context windows are a million tokens now. The original constraint is gone. HTML’s display power wins.
What it means for you: if you use Claude Code, switching system prompts to ask for HTML may improve the readability and reusability of what the agent produces. Tradeoffs apply.

For most of 2023 and 2024, every AI chat output looked the same. Bullet lists with bold headers. Three-asterisk dividers. Code fenced in triple backticks. That visual signature is Markdown, and Markdown became the default because it was the cheapest way to communicate structured information when context windows were 4,000 tokens and every character cost you something.

Thariq Shihipar’s argument is that the constraint changed and the default did not. Context windows in 2026 are a million tokens or more. The few-bytes-of-overhead-per-paragraph cost that made Markdown the obvious choice is now noise. HTML is more expressive, more visually capable, and, in his words, more effective for what humans actually read.

Who is Thariq Shihipar and why does this matter?

Thariq is the engineering lead for Claude Code at Anthropic. His day job is making the tool that millions of developers use. When the person responsible for the format of Claude Code’s outputs publishes a 2,000-word essay arguing the format should change, the AI engineering community pays attention. The post hit 4.4 million views in 16 hours and 8 million in under a day. Hacker News, Threads, and LinkedIn all ran heated threads on it.

The reaction was not because the format change is technically novel. AI tools have been producing HTML since the start. The reaction was because a public Anthropic voice said the default-since-GPT-4 was the wrong default, and explained why with examples.

What is the actual argument?

Five points, paraphrased from the original essay.

Markdown was a constraint-era choice. Tiny context windows + token costs made every saved character matter. Markdown is the most compact way to express structure in text. That ship sailed when models got larger contexts.
Humans skim, not read. Most Claude Code outputs are skimmed, not read top-to-bottom. HTML offers more visual aids (color, font size, callouts, real tables, indentation, summary boxes) for skimmers than Markdown does.
HTML is portable. Paste HTML into a Notion doc, a Slack post that supports rich text, a confluence page, an email, an internal wiki, and the formatting holds. Markdown often degrades.
Code embeds work better. HTML’s syntax for code blocks supports per-line styling, copy buttons, and inline annotations in ways Markdown does not, once you are past plain rendering.
Anthropic uses it internally. The team writes plans, code reviews, design systems, and reports as HTML output from Claude Code. The article notes this is not a hypothetical; it is the working default.

What does the difference actually look like?

Same content, two formats. Here is a Markdown table:

| Format   | Best for             | Weakness              |
| -------- | -------------------- | --------------------- |
| Markdown | speed, portability   | limited visual range  |
| HTML     | display, callouts    | longer, less portable |

And the HTML equivalent:

<table style="border-collapse:collapse;">
  <thead><tr><th>Format</th><th>Best for</th><th>Weakness</th></tr></thead>
  <tbody>
    <tr><td>Markdown</td><td>speed, portability</td><td>limited visual range</td></tr>
    <tr><td>HTML</td><td>display, callouts</td><td>longer, less portable</td></tr>
  </tbody>
</table>

Markdown wins on character count. HTML wins on what it can do once rendered: real columns, styled rows, hover states, internal anchors, sticky headers in long outputs. In a 16-character context window that gap did not matter. In a 1,000,000-character context window it does.

What are the criticisms?

The post drew real pushback, especially on Hacker News and Substack. Three threads worth knowing.

Portability isn’t true everywhere. HTML works great inside Notion, Confluence, modern email clients, and rich-text Slack. It does not work in terminal-based dev environments, vim notes, or many command-line interfaces. Markdown does. Critics argued the post overstated portability and understated developer-environment friction.
HTML output is harder to parse programmatically. If your downstream tool ingests the AI output and post-processes it, Markdown’s regularity is a feature. HTML is much harder to reliably parse with simple regex.
The “Unreasonable Ineffectiveness of HTML” rebuttal. A Medium piece by Kurtis Redux argued that HTML actually performs worse in many real benchmarks because models drift on tag closing, attribute hygiene, and nesting depth. The token savings of Markdown are real and they buy reliability.

Both sides have valid arguments. The right answer for most teams will be context-dependent.

Should I switch my Claude Code prompts to HTML?

Try it for a week if you fit the profile. Most likely yes if all of the following are true:

Your outputs are read by humans in browser-based tools (Notion, Confluence, web docs, web Slack).
You produce long-form plans, code reviews, technical reports, or design docs.
You skim outputs more than you parse them.
You have access to Claude Sonnet 4.6 or higher with a large context window.

Stay on Markdown if:

Your outputs feed terminals, vim, or non-rich-text destinations.
You post-process the AI output with scripts that expect Markdown structure.
You rely on model behavior being deterministic on shorter outputs (HTML drift is real on smaller models).

For the broader Claude Code workflow, see our Claude Code advanced guide. For how Claude Code compares to other coding assistants, the Claude Code vs Cursor vs Copilot comparison is the head-to-head you want.

How do I actually change the output format?

Two lines in your system prompt. Most Claude Code installs let you set a per-project preference.

# Add to your CLAUDE.md or system prompt:
Output format: HTML
Use semantic HTML tags. Include color callouts for warnings and tips.
Prefer real <table> elements over Markdown pipe tables.

If you run on Claude.ai (the web app) you can adjust the same way in your Project’s custom instructions. Anthropic has not yet shipped a one-click “HTML mode” toggle, but the engineering team has signaled this is on the roadmap.

Why does this matter beyond Claude Code?

Three reasons.

The post resets a default. Defaults compound. If Claude Code shifts to HTML as the recommended format, the AI agent tooling ecosystem will follow on a lag, and the visual feel of AI outputs in 2027 will look different from the visual feel of 2025.
It is a public engineering admission. Anthropic admitted publicly that a choice it had been making by default was the wrong one. That kind of in-the-open course-correction is rare and worth noticing.
It changes what “good prompt engineering” looks like. The “good prompt engineer” knows what format to ask for. Adding format specification to your prompts becomes a more impactful lever as model capability rises.

Beginners in AI position:

Output format is a small lever that most users have never thought about. The most useful immediate action is to try one week of HTML output in Claude Code if you use it daily. Measure the experience yourself. If the outputs are more useful, stay on HTML. If not, switch back. The strongest argument in the post is not that HTML is universally better, but that the default deserves to be reconsidered now that the constraint that produced it is gone.

Common questions about HTML vs Markdown in Claude Code

Will Anthropic make HTML the new default?

Not announced. The post is one engineer’s strong opinion, not a product change announcement. Anthropic has signaled the idea is being discussed but the per-user default for Claude.ai or Claude Code has not changed as of late May 2026.

Does this apply to ChatGPT and Gemini too?

The argument is format-portable, not model-specific. Try the same system prompt change on ChatGPT or Gemini and the underlying reasoning holds. Both models output HTML cleanly when asked. The difference is just whether your destination tool renders it well.

What about token cost?

HTML is roughly 1.5x to 3x the token count of Markdown for the same content. With Claude Sonnet 4.6 at $3 per million input tokens and $15 per million output, that means slightly higher per-message costs in HTML mode. For most workflows the cost increase is small (a few cents per long output). For high-volume agent workflows it adds up faster.

Is HTML safer or riskier from a security standpoint?

Slightly riskier in the sense that HTML allows script tags and event handlers that Markdown does not. If you trust your downstream rendering tool to sanitize HTML (most modern wikis, Notion, etc. do), this is a non-issue. If you are taking AI output and inserting it raw into a public web page, sanitize first.

Where can I read the original post?

Anthropic published it at claude.com/blog. The Simon Willison summary is also worth reading; he annotated the most important paragraphs and added his own pushback in places. Hacker News has the most thorough technical debate.

Sources

Get Smarter About AI Every Morning

Free daily newsletter. Built for people who want to use AI well, not chase every model.

Free forever. Unsubscribe anytime.

Best AI Wearables Compared (2026)

Cabinet AI: We Set Up an Agent Team

Adobe Firefly Video Explained