The Unreasonable Effectiveness of HTML: Why Claude Code Engineers Switched From Markdown

A close read of the argument that broke the AI dev community's biggest unexamined default — and a practical playbook for using HTML artifacts in your own work.

The headline you keep seeing

If you've spent any time on AI dev Twitter in the last two weeks, you've seen the phrase: "HTML is the new Markdown." The line is borrowed from Thariq Shihipar, an engineer on Anthropic's Claude Code team, whose May 2026 essay reframed the default output format question for the entire AI engineering community.

This piece is a careful read of his argument, what it gets right, where it should be qualified, and how to apply it without going overboard.

Why Markdown won in the first place

Markdown didn't become the AI default because it was the best output format. It became the default because it was the least bad format for a specific historical moment.

That moment was 2022–2024, the GPT-3.5 and early GPT-4 era. Context windows were 4K, then 8K, then 16K tokens. Every token mattered. Markdown's syntax is whitespace-friendly and ratio-efficient — a header is two characters, a list item is two characters, bold is four characters of overhead.

HTML, by contrast, is verbose. <h1>Title</h1> is 13 characters of overhead to wrap 5 characters of content. At 8K tokens, that overhead was actively painful. At 1M tokens, it's a rounding error.

The constraint that disappeared

The frontier models of mid-2026 — Claude Opus 4.7, Gemini 3, GPT-5.5 — operate in hundreds-of-thousands to millions of tokens. Most user-facing tasks don't come close to filling the window. Token efficiency stopped being the binding constraint a year ago. The default it imposed survived because nobody questioned it.

Thariq's contribution was to question it out loud, with examples, on a platform where the AI engineering community could see it. The reaction — hundreds of thousands of views, thousands of bookmarks, a wave of follow-up posts — confirmed that he was naming something a lot of people had been quietly noticing.

What HTML unlocks (the concrete list)

Here are the specific affordances HTML gives you that Markdown doesn't, with examples of when each one matters:

Inline annotations and margin notes

A code review in Markdown is a numbered list of issues. A code review in HTML is the actual diff rendered with color-coded annotations in the margin. The same information is 40x faster to absorb because the spatial relationship between finding and code is preserved.

Severity color-coding

"Critical / High / Medium / Low" labels in Markdown are textual. In HTML, they're red / orange / yellow / green pills next to the issue. Your eye finds the critical issues in 1 second instead of 30.

Sortable, filterable tables

A 50-row Markdown table is unreadable. The same data in an HTML table with sort buttons is immediately useful. Same content, totally different ergonomic surface.

SVG diagrams

Ask Claude for an architecture diagram in Markdown and you get ASCII boxes. Ask in HTML/SVG and you get an actual diagram with shapes, labels, arrows, and color. The cognitive load difference is enormous.

Tabs and accordions

A 5,000-word Markdown plan is a wall of text. A 5,000-word HTML plan with tabs for "Plan / Risks / Open Questions / Appendix" is navigable. Information architecture isn't a luxury — it's how humans actually read long documents.

Scroll-triggered storytelling

For status updates, reports, and presentations, scroll-triggered reveals turn a static doc into a guided tour. Markdown can't do this. HTML does it natively.

Interactive widgets

A pricing calculator. A live API tester. A "drag the slider to see how this metric changes" interaction. These take 10 seconds to add to an HTML artifact and add disproportionate value to the human reading the page.

A worked example: the PR review

Thariq's most-quoted concrete prompt:

"Help me review this PR by creating an HTML artifact that describes it. Render the actual diff with inline margin annotations, color-code findings by severity, and include a summary section at the top with overall risk assessment."

Run that against Claude Code and you get back a single HTML file. Open it in a browser. The diff is colored. The annotations are positioned. The severity is visible at a glance. The summary is at the top.

Now compare that to the Markdown equivalent: a numbered list with quoted code blocks. Same information. Five times the cognitive load to parse.

Where HTML is not the answer

Worth being honest about: this isn't a "use HTML for everything" argument. There are still cases where Markdown wins.

Agent-to-agent state: . When the consumer of an output is another model that will read it back as context, Markdown is more token-efficient and equally legible to the model.
Source-controlled docs: . README files, CONTRIBUTING guides, and anything that lives in git diffs benefits from Markdown's plain-text legibility in PRs.
Quick chat replies: . When the agent is responding to a one-off question, an HTML artifact is overkill. Markdown is fine.
Long-term knowledge bases: . If something needs to be greppable, indexable, and editable across years, plain text wins.

The right framing is HTML for delivery, Markdown for thinking. Use Markdown when the output is going back into the agent loop. Use HTML when the output is going to a human's eyeballs.

The publishing problem

If you adopt the HTML-artifact pattern, you immediately hit a logistical problem: HTML artifacts don't share well. You can't paste an HTML file into Slack. You can't email it as an attachment without losing its interactivity. You can't project it from a coworker's machine without sending them the file first.

This is where the publishing layer matters. host-html was designed for exactly this gap:

# From an agent or a script
HOSTHTML_API_KEY="hh_YOUR_API_KEY"
curl -X POST https://suifgsvtcbrawzdhyuhk.supabase.co/functions/v1/publish \
  -H "Authorization: Bearer $HOSTHTML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "..."}'

You get a URL back. The agent can paste it in chat. You can share it anywhere a link works — which is everywhere a human collaborates.

Or use the agent skill:

npx skills add phanosh/host-html --skill hosthtml-publish -g -y

Then the agent publishes inside the conversation. No copy-paste of HTML strings. No deploy pipelines. Generate → publish → share.

The pattern, in one workflow

Putting it all together, the practical workflow for the HTML-artifact era looks like this:

1. Ask in HTML by default for human-facing artifacts. Add to your prompts: "as a single self-contained HTML file."

2. Use Markdown for the thinking layer. When the agent is planning, reasoning, or talking to itself, let it stay in Markdown.

3. Publish HTML artifacts automatically. Wire your agent to host-html (skill or REST) so the artifact gets a URL the moment it's generated.

4. Share the URL, not the file. Slack, email, meetings — all consume URLs, not .html attachments.

The mental model: the agent produces artifacts, and an artifact isn't done until it has a URL.

What changes if this becomes the new default

If the industry adopts HTML-as-default for human-facing AI output, a few second-order effects look likely:

More agents will ship with built-in publishing skills.: Generating HTML and not publishing it is half a solution.
Markdown retreats to its real best-fit zone.: Agent-to-agent communication, README files, log streams. Not user-facing reports.
The bar for "what counts as an output" rises.: A Markdown list of bullet points stops being acceptable as a deliverable. An interactive HTML artifact becomes the baseline.
Visual design literacy matters more for engineers.: When your agent can produce any HTML you can describe, taste becomes the gating factor.

Try it once and feel the difference

The easiest way to internalize the argument is to do it once:

1. Take a recent task where you generated a Markdown output (a report, a plan, a status update, anything)

2. Re-ask the same agent for the same content as a single self-contained HTML file with appropriate visual hierarchy

3. Publish it on host-html, get a URL

4. Open both versions side by side

The HTML version isn't 10% better. It's a different category of artifact. That moment of comparison is what made the argument viral.