Markdown has become the dominant file format used by agents to communicate with us. It's simple, portable, has some rich text capability, and is easy for you to edit. Claude has even gotten surprisingly good at using ASCII to make diagrams inside of markdown files.
But as agents have become more and more powerful, I have felt that markdown has become a restricting format. I find it difficult to read a markdown file of more than a hundred lines. I want richer visualizations, color and diagrams, and I want to be able to share them easily.
I'm also increasingly not editing these files myself, but using them as specs, reference files, brainstorming outputs. When I do make edits, I'm usually prompting Claude to edit them, which removes one of markdown's largest benefits.
I've started preferring HTML as an output format instead of Markdown, and increasingly see this being used by others on the Claude Code team. This is why.
Why HTML?
Information Density
HTML can convey much richer information compared to markdown. It can do simple document structure like headers and formatting, but it can also represent all sorts of other information:
- Tabular data using tables
- Design data with CSS
- Illustrations with SVG
- Code snippets with
<script>tags - Interactions using HTML elements with JavaScript and CSS
- Workflows using SVG and HTML
- Spatial data using absolute positions and canvases
- Images using image tags
I would go so far as to say there is almost no set of information Claude can read that you cannot fairly efficiently represent with HTML.
In the absence of being able to do this, the model may do more inefficient things in markdown — like ASCII diagrams or, my favorite, estimating colors with unicode characters:
Visual Clarity & Ease of Reading
As Claude is able to do more complex work, it's also writing larger and larger specs and plans. In practice, I've found I tend not to actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it.
HTML documents are much easier to read. Claude can organize the structure visually to be ideal to navigate — with tabs, illustrations, links. It can even be mobile-responsive, so you can read it differently based on your form factor.
Cream is warm enough to feel printed. Vermillion stays under 5% of the page.
Two-way Interaction
HTML can let you interact with the document. You might ask Claude to add sliders or knobs to adjust a design, or let you tweak different options in an algorithm to see what happens. You can also ask it to give you a button that copies these changes back into a prompt to paste into Claude Code.
Make the arrow rotate 0° with length 100%.
Read more about my playgrounds post to see examples of this kind of two-way interaction.
Data Ingestion
Why use Claude Code to make HTML files instead of Claude.ai or Claude Design? One of the biggest reasons is all the context Claude Code can ingest.
For example, when writing this article, I asked Claude Code to read through my code folder, find all the HTML files I've generated, group and categorize them, then make an HTML file with diagrams representing each type. The diagrams you see in this article are a direct result.
Besides the file system, Claude Code can find additional context using your MCPs (like Slack, Linear), your web browser (with Claude in Chrome), your git history, and more.
It's Joyful ↗
Making HTML documents with Claude is just more fun, and makes me feel more involved and invested in the creation. That, by itself, is enough.
(Try clicking the heading.)
How to get started
I'm a little bit afraid people will read this and turn it into a /html skill. While there might be value in that, I want to emphasize that you don't need to do much to get Claude to do this. You can just ask it to "make an HTML file" or "make an HTML artifact."
The trick is knowing what you want the artifact to do and how you might use it. You may over time make a skill, but for now I'd suggest just prompting from scratch to get a hang of how to use it in different cases.
Use cases
To make this more concrete, I've made many different HTML files for different use cases. Here's an overview.
Specs, planning & exploration
HTML is a rich canvas for Claude to dive into a problem. When I start working on something, instead of a simple markdown plan I expect to make a web of HTML files. I might start by asking Claude to brainstorm and create explorations of different options. I'd then ask it to expand on one — make mockups, code snippets. Finally, when I feel good, I'll ask it to write an implementation plan. When I'm happy, I'll create a new session and pass in all of these files for it to implement.
When verifying I'll also ask the verification agent to read the files; it has much broader context on what's needed.
Code review & understanding
Code can be difficult to read in a markdown file. With HTML we can render diffs, annotations, flowcharts, modules. Use this to understand code an agent has written, to get code review, or to explain a PR to a reviewer. I find this often works better than the default GitHub diff view, and I attach an HTML code explainer to every PR I make now.
Design & prototypes
Claude Design is based on HTML because HTML is incredibly expressive at design — even if your end surface is not HTML. Claude can sketch a design in HTML and then write it in your language of choice (React, Swift, etc.).
You can also prototype interactions: animations, actions. Consider asking Claude to make sliders and knobs to tune in exactly what you're looking for.
Reports, research & learning
Claude Code is incredibly good at synthesizing information across multiple data sources and converting it into a report. You can prompt it to search Slack, the codebase, git history, the web, and use that to generate extremely readable reports for yourself, leadership, or your team.
You could assemble this as a long HTML document, an interactive explainer, or even a slideshow. Ask Claude to use SVG for diagrams.
For my posts on prompt caching, I asked Claude to prepare an in-depth research file in HTML for me to read after reading the git history.
Custom editing interfaces
Sometimes it's hard to describe what you want purely in a text box. In that case, I'll ask Claude to build me a throwaway editor for the exact thing I'm working on. Not a product, or a reusable tool — a single HTML file, purpose-built for this one piece of data.
The trick is always to end with an export: a "copy as JSON" or "copy as prompt" button that turns whatever I did in the UI back into something I can paste into Claude Code.
Frequently asked questions
I've been telling many people I've switched to HTML, and a few questions repeat.
Isn't it less token-efficient?
Markdown often uses fewer tokens, but I've found the added expressiveness of HTML and the much higher likelihood of me actually reading it means I get overall better output. With the 1MM context window in Opus 4.7, the increased token usage isn't really noticeable.
When do you use markdown for now?
Honestly I've mostly stopped using markdown for almost everything, but I'm probably far on the HTML-maximalist side of things.
How do I view the HTML file?
I tend to just open it in a browser locally (you can ask Claude to open it), or upload to S3 if you want a shareable link.
Doesn't this take longer to generate than markdown?
It does! HTML can take 2–4× longer than markdown, but I've found the results are worth it.
What about version control?
Honestly one of the biggest downsides of HTML — diffs are noisy and hard to review compared to markdown.
How do I get Claude to match my taste / not make it ugly?
The frontend-design plugin helps Claude make good HTML files. To match your company's style, you can create a single design-system HTML file by pointing Claude at your codebase, then use that file as a reference for other HTML files.
Stay in the loop
All of the above is to say: I think the real reason I use HTML is that I feel much more in the loop with Claude. I had begun to fear that because I had stopped reading plans in depth, I would simply have to leave Claude to make its choices.
But I'm happy to say I feel more in the loop than ever before when using HTML. I hope you do too.