Anthropic's Claude Code team just published a case for HTML over Markdown — here's why it matters for production tooling

Thariq Shihipar, who works on the Claude Code team at Anthropic, published a piece yesterday titled The Unreasonable Effectiveness of HTML. The argument: when you need structured output from Claude, request HTML instead of Markdown. The reasoning is simple — HTML gives you layout control, inline styles, tables that don't break, and interactive elements. Markdown gives you headings and bullets.

We've been doing this in VioX OS since November 2025. Not because we read a blog post, but because we kept hitting the same constraint: Markdown falls apart the moment you need anything beyond paragraphs and lists. Client CRM dashboards, multi-column invoice layouts, interactive agent logs with collapsible detail sections — none of that works in Markdown. HTML does.

Shihipar's examples are good. He shows Claude generating comparison tables, color-coded diff views, interactive PR summaries with expand/collapse sections. All of this would be painful or impossible in Markdown. The prompt pattern he suggests is straightforward: "Create an HTML artifact that describes this PR" instead of "Summarize this PR." The model returns a <div> block with inline CSS. You render it directly.

The interesting part is why this works so well. HTML is a layout language. Markdown is a shorthand for a subset of HTML. When you ask an LLM to generate Markdown, you're asking it to use a tool with fewer primitives. The model can't express "put these two columns side by side" or "make this row red if the value is negative" in Markdown. It has to either ignore the requirement or generate something that doesn't render how you want.

HTML doesn't have that problem. The model has access to the full layout vocabulary — flexbox, grid, inline styles, <details> for collapsible sections, <table> for actual tables instead of ASCII art. The output quality jumps because the tool fits the task.

What this looks like in production

VioX OS generates a lot of structured output. Agent call logs, CRM activity feeds, invoice line-item breakdowns, appointment scheduling summaries. We tried Markdown first. It worked for simple cases — a bulleted list of completed tasks, a paragraph summary of a call. It broke the moment we needed layout.

Example: DreamersJoy's order confirmation page. The client sends an order; the agent generates a confirmation artifact. The artifact needs to show order details in two columns (left: item list with quantities and prices; right: delivery address and timeline), a totals table at the bottom, and a collapsible section for special instructions. Markdown can't do that. HTML can.

The prompt we use: "Generate an HTML artifact for this order confirmation. Use a two-column layout with flexbox. Include inline CSS. Make the special instructions section collapsible using a <details> tag." Claude 3.7 Sonnet returns valid HTML 95% of the time. We render it in an iframe with a sandboxed content security policy. The client sees a formatted confirmation page that looks like we hand-coded it.

Another case: agent call logs. We generate a timeline view with each call step as a row. Steps that succeeded are green; steps that failed or were skipped are gray. Each row has a timestamp, a status badge, and a collapsible detail section with the raw transcript. Markdown can't express that. HTML can. The prompt asks for a vertical timeline using <div> blocks with inline styles and <details> tags for the transcripts. Works.

The tradeoff

HTML output is more powerful, but it's also more dangerous. If you're rendering user-generated HTML, you need a CSP that strips <script> tags, external resource loads, and inline event handlers. We use a strict CSP in the iframe: default-src 'none'; style-src 'unsafe-inline';. That blocks everything except inline CSS. It's enough.

The other tradeoff: HTML is harder to validate. Markdown is simple enough that you can write a quick regex to check for common mistakes (unclosed brackets, broken links). HTML has more surface area. We don't validate the HTML before rendering it; we rely on the browser's parser to handle malformed tags gracefully. So far, Claude generates valid HTML often enough that this hasn't been a problem.

Shihipar's article includes a note about accessibility. HTML gives you semantic tags (<nav>, <article>, <section>) and ARIA attributes. Markdown doesn't. If you're generating output that needs to be screen-reader friendly, HTML is the only option.

When to stick with Markdown

Markdown still wins for simple cases. If you need a paragraph summary or a bulleted list, Markdown is cleaner. It's easier to store, easier to diff, easier to edit manually if the model gets something wrong. We still use Markdown for agent chat transcripts, blog post drafts, and plain-text summaries.

The heuristic: if the output needs layout, use HTML. If it's just text and lists, use Markdown.

Shihipar's piece includes a live demo site with 15+ examples. Worth clicking through if you're building anything that generates structured output from Claude. The examples are practical — PR summaries, documentation pages, data tables, comparison grids. All of them would be worse in Markdown.

We've been running HTML output in VioX OS for six months across 12 client deployments. It works. The quality jump from Markdown to HTML is real. If you're still generating Markdown by default, try HTML for one use case and see what happens.