Claude Code HTML Output vs Markdown: A 2026 Practical Guide for AI Coding
The Prompt Engineering Shift Nobody Warned You About
For two years, the standard advice was straightforward: ask AI for code in Markdown, keep your prompts short, and format your outputs around backticks and code fences. That advice is starting to rot.
Thariq Shihipar, a member of Anthropic’s Claude Code team, published a piece in early May 2026 that has been quietly reshaping how power users talk to AI coding tools. His argument is simple but its implications are large: HTML is a better output format than Markdown when you’re working with an AI that can generate rich, structured content. And once you start asking the right way, it’s hard to go back.
The old logic made sense when context windows were small and token budgets were precious. Markdown compressed better. But with models now routinely running 200K tokens and beyond, that efficiency argument has collapsed. What hasn’t collapsed is the quality gap between what a model produces in Markdown versus what it can produce as a self-contained HTML document.
What Changes When You Ask for HTML Instead
When you request output in HTML, something interesting happens — the model’s response stops being a wall of text with some formatting and starts being a document with actual structure. You get SVG diagrams rendered inline, CSS styling that makes data readable at a glance, interactive widgets embedded directly in the page, and in-page navigation that lets you jump between sections without scrolling through everything.
Simon Willison tried this approach after reading Thariq’s piece. He used GPT-5.5 to explain a Linux security exploit, asking it to output HTML with styling and JavaScript to make the explanation interactive. The resulting page was something you’d actually want to send to a colleague — not a ChatGPT screenshot.
This isn’t just about aesthetics. It’s about comprehension. A color-coded diff with severity annotations communicated the security issue faster than any equivalent Markdown block would have. The model used CSS classes to distinguish critical issues from warnings, and embedded a mini navigation bar so the reader could jump directly to the section that mattered to them.
A Prompt That Actually Works
Here is the pattern Thariq recommends in his post:
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.Notice what this prompt does that a standard coding request does not: it specifies the medium (HTML artifact), the structure (diff with margin annotations), the visual encoding (color-coded by severity), and the audience (someone unfamiliar with the specific logic). The specificity is the point — it gives the model something concrete to design around.
The Concrete Use Cases Where HTML Artifacts Win
This isn't a universal upgrade. HTML output shines most in situations where the information has spatial or visual relationships that Markdown just can't express cleanly:
- Code review summaries — Diff output with color-coded severity, inline margin notes, collapsible sections for files you don't need to examine closely
- Architecture explanations — Component diagrams in SVG, interactive dependency graphs, clickable module maps
- Data analysis reports — Tables with conditional formatting, inline charts rendered in SVG or Canvas, filter controls
- Security findings — Exploit breakdowns with code annotated in severity tiers, call graphs, remediation checklists
- API documentation — Interactive request/response explorers, parameter tables with types and constraints, try-it-out forms
The common thread is that all of these involve structured, multi-level information where spatial layout and visual encoding carry real meaning.
The Old Workflow and Why It Breaks Down
The classic flow goes like this: you ask a coding AI to explain something, it responds in Markdown, you paste it into a README or copy it into Slack, and the recipient has to read through a wall of formatted text to find what matters to them. The model did its best with the format it was given, but Markdown is fundamentally a publishing format for prose — not a layout engine for structured technical information.
Here's what you actually lose in that exchange: visual hierarchy that guides the eye, color as a signal (not just decoration), interactive elements that let the reader test things themselves, and navigation that respects the reader's time by letting them jump to relevant sections.
For simple explanations, that's fine. But as soon as the information has any real complexity — multiple files, interlinked concepts, severity gradations — Markdown starts working against you. You're forcing the model to communicate something complex through a medium that's optimized for something simple.
How to Ask for HTML Output: Practical Patterns
You don't need to change everything at once. The shift happens in how you frame the request. Here are the patterns that have proven themselves in production workflows this year:
1. Specify the Audience First
"Explain this code to a junior developer who has never seen async/await before" produces very different output than "explain this to a senior engineer reviewing it for security issues." HTML gives the model room to adjust depth and visual complexity — use that.
2. Describe the Structure You Want, Not Just the Content
"Create an HTML page with a sticky header showing the file tree on the left and the code view on the right, with syntax highlighting that uses the GitHub Dark color scheme." That's a layout description, and it's instructions the model can actually follow.
3. Use SVG When You're Explaining Relationships
Requesting "include an SVG call graph showing the dependency chain" unlocks diagrams that Markdown simply cannot express. The model will generate the SVG markup, and modern browsers render it without any build step.
4. Keep CSS Inline for Portability
Ask for everything in one file. No external stylesheets, no separate JavaScript files — the whole artifact should be copy-pasteable as a single HTML document that works in any browser.
When to Stick With Markdown
HTML output isn't always the right call, and knowing when to use it matters as much as knowing when to reach for it:
- Quick debugging questions — When you just need a fast answer to a specific line of code, standard Markdown responses are faster to read
- Git commit messages — These need to live in git log and git blame, where Markdown renders natively
- Situation where the reader can't open HTML — Some security contexts block HTML attachments; Markdown is universally safe
- Very short, linear explanations — If the explanation has no branching structure and doesn't need visual encoding, Markdown's simplicity wins
The Tooling Reality: What You Actually Need
One practical concern that comes up immediately: if the model outputs a 500-line HTML artifact, how do you use it? The answer is that you copy it straight into a .html file or paste it into a tool like this collection of examples that Thariq maintains to demonstrate the approach.
For most users, the workflow is: ask for HTML → model produces an artifact → save as .html → open in browser. That's it. No build step, no special tooling, no deployment. The browser is your viewer, and it handles everything the model put into the file.
For Claude Code users specifically, the artifacts feature already supports HTML output — you don't need to configure anything special. Just ask clearly for what you want in the output.
The Bigger Point: Output Format Shapes Thinking
The most interesting observation in Thariq's post isn't technical — it's about cognitive load. When a model knows it's producing HTML, it designs information for a medium that supports layout, hierarchy, and interactivity. When it knows it's producing Markdown, it designs for a medium that supports headings, bold text, and code fences.
Those sound like small differences, but they compound. A model thinking in HTML is a model thinking about spatial relationships, visual signals, and interactive exploration. A model thinking in Markdown is a model thinking about prose flow and formatting syntax. For technical documentation, the former produces something more useful. For prose essays, the latter is still fine.
This is a case where the technology has outgrown the convention. We settled on Markdown because of token limits that no longer exist in the same way. The models got bigger. The context windows got wider. The output format we've been using since 2023 is a product of constraints that have moved.
What Thariq and Willison are pointing at is that the easiest way to get better output from these models might not be a new model or a new technique — it's changing the format you ask for. Ask for HTML. See what happens.
FAQ
Doesn't HTML use more tokens than Markdown? Won't that hurt performance?
Yes, HTML is more verbose — but with models running 200K+ token context windows, the efficiency argument for Markdown has largely evaporated. If anything, the richer output saves you time downstream by reducing back-and-forth clarification.
Can I use this with any AI model, or is this Claude-specific?
The HTML-first approach works with any model that can generate well-structured HTML output. Claude Code's artifacts feature makes it especially smooth, but GPT-4 and Gemini can also produce HTML artifacts — you just need to ask explicitly.
What about styling? I don't want the output to look generic.
You can ask the model to include inline CSS. Something like "use a minimal dark theme with monospace fonts for code" or "apply a clean documentation style inspired by Stripe's API reference" gives the model a visual target to aim at.
Is this approach published anywhere as a formal technique?
Thariq Shihipar's post on the Claude Code team's blog is the main reference. Simon Willison's write-up of his experience using it is also worth reading. There isn't a formal name yet — it's still being discussed in blog posts rather than formal papers — but the pattern is spreading fast among power users.