Q&A: The Unreasonable Effectiveness of HTML¶

Article: simon-willison-unreasonable-effectiveness-html
Author: Simon Willison
Published: May 8, 2026
Source: https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/

Q1: If Markdown was good enough for years, why switch now — what changed?¶

The short answer: token limits went from scarce to abundant.

Markdown became the default output format during the GPT-4 era (8,192 token context windows), when every token counted against a hard ceiling. Markdown's compact syntax was measurably more token-efficient than HTML — you could express the same information in fewer tokens using Markdown's lightweight markup.

Modern LLMs now support context windows that make that efficiency gain irrelevant. When you're working with 128K+ tokens, saving 200 tokens on formatting is noise, not a constraint. The token budget that made Markdown necessary has evaporated.

Thariq Shihipar's piece (on Anthropic's Claude Code team) made the case that HTML as an artifact — a self-contained, styled, interactive document — is a far richer output format than any Markdown block could produce. Simon Willison accepted the argument and is now defaulting to HTML for ad-hoc explanations.

Q2: What specific HTML capabilities make it superior to Markdown for AI output?¶

HTML enables several output dimensions that Markdown structurally cannot express:

Visual encoding:
- Color-coded severity levels (not just text labels like "HIGH/MEDIUM/LOW")
- Diff highlighting with red/green inline rendering
- Margin annotations alongside code without corrupting the code itself

Rich structure:
- Collapsible sections and tabbed content for layered explanations
- Sticky headers and in-page navigation (jump links, table of contents)
- Multi-column layouts for comparing related information side by side

Embedded media:
- Inline SVG diagrams that visualize concepts without external hosting
- Embedded interactive widgets (JavaScript-powered, self-contained)
- Styled typography that's readable in a browser, not just a terminal

The copy.fail example demonstrates this concretely: an obfuscated Linux exploit explained via curl | llm prompt — the resulting HTML page rendered the exploit with formatting that a Markdown code block simply cannot replicate.

Q3: How does this interact with the broader shift in agentic engineering toward richer outputs?¶

This is the same directional shift described in simon-w-agentic-engineering-patterns — from text output to structured, multi-modal, interactive artifacts.

Agentic engineering's "write code is cheap now" insight extends naturally: rendering rich output is cheap now too. The constraint that kept outputs text-only (token efficiency) is gone. The next constraint is comprehension speed — an operator reviewing a PR needs to parse severity, structure, and relationships fast.

An HTML artifact with:
- Inline SVG callouts showing data flow
- Color-coded diff annotations
- Collapsible sections for deep-dive detail
- Sticky navigation for jumping between sections

...delivers faster comprehension than the equivalent Markdown, for the same reason a well-designed dashboard beats a table of numbers: visual encoding of information reduces cognitive load.

The pattern also connects to factory quality gates: kelly-factory-overview QA operations that currently rely on Markdown diffs could produce HTML review artifacts with margin annotations and severity highlighting — reducing operator review time while capturing more structural information about the change.

See also: simon-willison-unreasonable-effectiveness-html for the full source article.