The Unreasonable Effectiveness of HTML: Why You Should Make Claude Code Output HTML, Not Markdown

6 min read

For years, the default output format for AI coding assistants has been Markdown. It's lightweight, readable, and token-efficient. But Markdown is leaving capability on the table.

In a thought-provoking post that hit #1 on Hacker News today, Thariq Shihipar (who works on the Claude Code team at Anthropic) made a compelling case for switching to HTML. His thesis: when you ask Claude for HTML instead of Markdown, the quality and richness of what you get back leaps dramatically.

Simon Willison picked it up on his blog, calling it a "thought-provoking piece" that changed how he thinks about AI output formats. And the HN community agrees — the thread has over 138 points in just a few hours.

Let me show you why this matters and how to do it right.

The Problem with Markdown-Only Output

Markdown was designed for simple text formatting — headings, lists, links, and the occasional code block. It's great for READMEs. But when Claude is trying to explain something complex, Markdown forces it into a flat, linear format.

Consider what happens when you ask Claude to explain a PR diff:

The difference isn't incremental. It's transformative.

⚡ The Key Insight: HTML is the universal runtime. Every modern LLM can write it flawlessly, and every browser renders it instantly. No build step. No dependencies. Just raw capability.

What HTML Unlocks

When Claude generates HTML, it can include:

  • SVG diagrams — architecture flowcharts, sequence diagrams, state machines rendered inline
  • Interactive widgets — collapsible sections, tabbed panels, live data tables with sorting
  • In-page navigation — linked table of contents, anchor jumps, floating sidebars
  • Rich annotations — margin notes on code, tooltip definitions, color-coded severity markers
  • CSS layouts — grids, columns, responsive designs that make complex information browsable

You're not just getting text. You're getting a fully styled, navigable document — and Claude generates all of it in a single pass.

Prompt Templates That Work

Here are specific prompts that unlock HTML output effectively:

PR Review with Rich Annotations

Help me review this PR by creating an HTML artifact that describes it.
I'm not very familiar with the streaming/backpressure logic so focus on that.
Render the actual diff with inline margin annotations, color-code findings
by severity, and whatever else might be needed to convey the concept well.

Code Deep-Dive with Interactive Diagrams

Explain this code in detail. Reformat it, expand out confusing parts,
and go deep into what it does. Output HTML, neatly styled using CSS,
and use SVG for diagrams to make the explanation visual and interactive.

Architecture Documentation

Document this system architecture as a single HTML page.
Include an SVG architecture diagram, a component dependency graph,
and color-coded service boundaries. Make it self-contained.

Simon Willison tried this approach against a complex Linux kernel exploit (copy.fail) with impressive results: GPT-5.5 generated a complete HTML explainer with neatly styled code blocks, expandable sections, and clear visual hierarchy.

When to Use HTML vs. Markdown

Use Markdown Use HTML README files PR review explanations Quick notes & summaries Complex code analysis GitHub/GitLab docs Architecture deep-dives Internal comments Security exploit walkthroughs Token-constrained contexts Debugging session summaries

The rule of thumb: if you'd benefit from diagrams, layout, or interactivity, ask for HTML.

Practical Tips

1. Be Specific About Richness

Don't just say "output HTML." Tell Claude what kind of richness you want: SVG diagrams, collapsible sections, color-coding, annotations, etc. The more specific your ask, the better the output.

2. Use the HTML Artifact Feature

Both Claude Code and Claude.ai support HTML artifacts — rendered previews within the chat interface. When Claude generates HTML, you can preview it live. This makes the feedback loop much faster.

3. Pipe via curl for Batch Processing

Simon Willison demonstrated a pro trick: pipe content via curl directly into an LLM with an HTML output instruction:

curl https://example.com/exploit.py | llm -m gpt-5.5 -s \
  'Explain this code in detail. Output HTML, neatly styled and
   using capabilities of HTML and CSS to make the explanation
   rich and interactive.'

4. Remember: Token Cost vs. Value

HTML output uses more tokens than Markdown — roughly 40-60% more for equivalent content. But the value per token is much higher. A 142-line SVG diagram conveys more understanding than pages of prose. Spend tokens where they deliver insight.

If you're on a tight context window (like the old GPT-4 8K era), Markdown's token efficiency mattered. Modern models have 200K+ context windows. That trade-off is largely gone.

Why This Is a 2026 Trend

Several forces make this shift timely:

  • Large context windows — the token premium for HTML is trivial at 200K
  • Code-generation quality — models write HTML/CSS/JS as fluently as Markdown now
  • Artifact previews — Claude Code and other tools render HTML inline in the chat
  • Self-contained files — a single HTML file with embedded CSS + SVG replaces multiple screenshots, diagrams, and documents

We're moving from "chat with text" to "chat with documents." HTML is the document format that AI agents natively produce and humans natively consume.

Conclusion

Thariq Shihipar's insight — that HTML is the unreasonably effective output format for AI coding agents — is one of those ideas that feels obvious in retrospect. Markdown was always a compromise. HTML is the real format. We just needed models good enough to make it practical.

We're there now. Ask for HTML. You'll be surprised at what you get back.

Resources