HTML as AI Output Format¶
In May 2026 an Anthropic engineering lead who works on Claude Code published a case that HTML — not Markdown — should be the default output format requested from AI agents for most non-trivial work. The argument went viral on X (10.1 million views, 14,200 likes, 28,300 bookmarks) and reached the #1 spot on Hacker News on May 9, triggering widespread discussion across developer communities (Thariq Shihipar via YouMind, 2026-05-08; Simon Willison, 2026-05-08; noqta.tn, 2026-05-10).
The Central Argument¶
Markdown won the early AI-assistant era for a clear reason: context windows were tiny. In the GPT-4 era, an 8,192-token cap made every HTML angle bracket a tax. That constraint is now gone. Modern models operate with context windows in the hundreds of thousands or millions of tokens, making the token-cost difference between HTML and Markdown largely irrelevant for output.
The argument is that Markdown has become a restricting format for agents that are doing increasingly complex work. A Markdown file longer than roughly 100 lines is difficult for a human to navigate. Agents forced to represent rich information in Markdown produce workarounds: ASCII art for diagrams, Unicode characters to approximate colours. HTML removes that constraint entirely.
Five Reasons HTML Beats Markdown for Agent Output¶
1. Information density. HTML can carry tables with real headers and alignment, SVG diagrams drawn directly in the document, executable code in <script> tags, interactive widgets (sliders, collapsible sections, in-page navigation), spatial layouts with absolute positioning or canvas, inline images in base64, and stylesheets scoped to the document. There is almost no information an agent can read that cannot be efficiently represented in HTML.
2. Visual clarity and navigability. As agents do more complex work, they produce larger specs and plans. An HTML document can be organised with tabs, illustrations, sticky headers, and jump links — it can even be made mobile-responsive. A colleague who would never read a 100-line Markdown file will read an HTML document that visually organises the same information.
3. Ease of sharing. Markdown files require attachments or raw rendering in a separate tool. An HTML file uploaded to any hosting service (S3, GitHub Pages) becomes a link. The chance someone actually reads the spec, code review, or PR writeup increases significantly when it is a link rather than a file attachment.
4. Two-way interaction. HTML supports real interaction: sliders to tune algorithm parameters, knobs to adjust a design, buttons to copy a modified prompt back into Claude Code. The output becomes a live tool rather than a static document.
5. Claude Code's rich context access. Claude Code can ingest the filesystem, MCPs (Slack, Linear, etc.), the web browser, and git history. Turning that combined context into an HTML artifact is almost always more expressive than a Markdown summary — the two modalities are not equivalent when the input context is rich.
20 Example Use Cases¶
The companion site at thariqs.github.io/html-effectiveness ships 20 self-contained HTML files generated by Claude Code, grouped into 9 categories:
| Category | Example artifacts |
|---|---|
| Exploration & planning | Code-approach comparisons, visual design directions, implementation plans with risk tables |
| Code review | Annotated pull requests with margin notes and severity tags, module maps as box-and-arrow diagrams, PR writeups with file-by-file tours |
| Design | Living design systems (colour swatches, type scale, spacing tokens), component variant sheets |
| Prototyping | Animation sandboxes with tunable easing, clickable user flows |
| Illustrations | SVG figure sheets, annotated flowcharts with click-to-reveal timings |
| Decks | Single-file slide presentations navigated with arrow keys |
| Research | Feature explainers with collapsible sections and tabbed code samples, concept explainers with live interactive rings |
| Reports | Weekly status reports with small charts, incident timelines with colour |
| Custom editing UIs | Triage boards, feature flag editors, prompt tuners |
Each artifact is a single .html file that opens directly in any browser — no build step, no framework, no server.
Example Prompts¶
The article includes several prompts that illustrate the pattern:
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.
Explain this code in detail. Reformat it, expand out any confusing bits and
go deep into what it does and how it works. Output HTML, neatly styled and
using capabilities of HTML and CSS and JavaScript to make the explanation
rich and interactive and as clear as possible.
Within hours of publication, a community-built Claude skill called html-artifacts appeared on GitHub, encoding the recommendations as a reusable instruction set: produce a self-contained HTML artifact whenever the task involves anything spatial, interactive, or visual; fall back to Markdown only for plain prose or short answers.
Counterarguments¶
The debate on Hacker News and X split roughly into three camps:
- Agent-first: Markdown is still the right format when one AI model is producing output for another. Lower token cost, easier parsing, deterministic structure. "Markdown for agents, HTML for humans" was one widely-upvoted summary.
- Practicality: GitHub Gists, Notion, Linear, and most chat tools render Markdown beautifully out of the box. An HTML file requires opening a tab, hosting, or embedding via iframe.
- Token economy: Richer HTML outputs are more expensive outputs. "Anthropic definitely wants us to spend more tokens on HTML instead of Markdown" was a cynical but widely shared framing.
The article does not refute these points; it focuses on the human-review scenario where the audience is a person reading a plan, spec, or report — not an automated pipeline consuming structured output.
Relationship to Claude Code Specifics¶
The author notes that Claude Code ingests context from many sources simultaneously: the filesystem, MCPs (Slack, Linear), the web browser via Claude in Chrome, and git history. Turning that multi-source context into an HTML artifact is almost always more expressive than a Markdown summary because the format can visually represent the relationships between sources rather than listing them linearly.
This has particular relevance for the wiki itself: if a wiki page is generated by an agent that has read multiple files and sources, HTML would allow cross-links, collapsible sections for each source, and colour-coded confidence levels in a way that flat Markdown cannot.
Limitations¶
The primary source is a personal post by an Anthropic engineer — authoritative about practice at Anthropic and on Claude Code specifically, but not a formal specification or published research. The community response is large and quick but primarily anecdotal; no systematic comparison of Markdown vs. HTML output quality is available. HTML files require a rendering context (a browser tab) that Markdown-native tools do not; for teams where the artefact lives in Notion, Confluence, or Linear, the benefit is reduced.
Changelog¶
2026-05-19 — Page created from three sources: Thariq Shihipar's companion site (Type B/C, Anthropic engineer), Simon Willison link post (trusted-author Type C), noqta.tn coverage (Type C). Confidence 78 moderate. Topics: HTML vs Markdown, five reasons, 20 example use cases, counterarguments.