Using HTML Instead of Markdown: Firsthand Practices from the Claude Code Team

*Using Claude Code: The Unreasonable Effectiveness of HTML*

Author: Thariq Shihipar (Engineering Lead for Anthropic Claude Code) | English version

Markdown has become the dominant file format used by agents to communicate with humans. It's simple, portable, has some rich text capability, and is easy to edit. Claude has even become surprisingly good at using ASCII to make diagrams in Markdown files.

Markdown has become the most commonly used file format for AI agents when communicating with humans. It is simple and portable, has some rich-text capabilities, and is easy to edit manually. Claude has even become quite adept at using ASCII to draw diagrams inside Markdown files.

But as agents have become more and more powerful, I've found that Markdown has become an increasingly restrictive format. Specifically, I find it difficult to read a Markdown file of more than a hundred lines; I want Claude to generate richer visualizations, color and diagrams; and I want to be able to share these outputs more easily.

But as AI agents become more powerful, Markdown has increasingly felt restrictive to me. In particular: I don’t have the patience to read Markdown files longer than about a hundred lines; I want Claude to generate richer visuals, colors, and charts; and I want to share outputs more easily.

I also am increasingly not editing these files myself, but using them as specs and reference files. When I do make edits, I'm usually prompting Claude to edit them, which removes one of Markdown's largest benefits.

Likewise, I’m editing these files myself less and less, and use them more as specs and reference materials. Even when I do edit, I usually ask Claude to make changes via prompts, which means Markdown’s biggest advantage—easy manual editing—no longer applies.

Instead, I've started preferring HTML as an output format instead of Markdown and increasingly see this pattern being applied by others on the Claude Code team. In this post, I share why and how our team uses HTML to produce richer, more readable Claude Code outputs.

Instead, I have started preferring HTML as an output format over Markdown, and I’m seeing more people on the Claude Code team adopt this approach. In this post, I share why and how our team uses HTML to produce richer and more readable Claude Code outputs.

If you’re just getting started with Claude Code, the CC Switch tool introduction can help you quickly switch among multiple Claude tools. For turning Claude capabilities into reusable Skills, you can refer to “Introduction to Skills”.

1. Why Use HTML?

A few things make HTML a better fit than Markdown for the kind of work I'm now doing with Claude Code.

These are the reasons HTML is better than Markdown for the work I’m doing with Claude Code today.

1. Information Density

HTML can convey much richer information compared to Markdown. It can, of course, do simple document structure like headers and formatting, but it can also represent all sorts of other information such as:

• Tabular data using tables
• Design data with CSS
• Illustrations with SVG
• Code snippets with script tags
• Interactions using HTML elements with JavaScript + CSS
• Workflows using SVG and HTML
• Spatial data using absolute positions and canvases
• Images using image tags

I even think that, for almost any information Claude can understand, there is almost no case that cannot be efficiently represented in HTML. This makes HTML a highly efficient way for the model to communicate deep information to you, and for you to review it.

In my opinion, there is almost no set of information that Claude can read that you cannot efficiently represent with HTML. This makes it a highly efficient way for the model to communicate in-depth information to you and for you to review it.

I’ve found that when this isn’t possible, the model may revert to less efficient Markdown workarounds, such as ASCII diagrams, or my favorite: trying to approximate color using Unicode characters.

I’ve found that when HTML is not available, the model often does less efficient things in Markdown, like ASCII diagrams—or, my least favorite, emulating color blocks with Unicode characters.

2. Visual Clarity and Ease of Reading

As Claude is capable of tackling more complex work, it's also able to write larger and larger specs and plans. I've found that I tend to not 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.

As Claude is able to take on more complex work, it also generates larger specs and plans. I’ve found that I typically don’t read Markdown files much beyond 100 lines—and I definitely can’t get other people on my team to read them either.

But HTML documents are much easier to read because Claude can organize the structure visually to be ideal to navigate with tabs, illustrations, and links. It can even be mobile responsive so you can read it differently based on your form factor.

HTML documents are much easier to read because Claude can visually organize structure for easier navigation with tabs, illustrations, and links. HTML can also be mobile-responsive, so the document adapts to different screen sizes and device form factors.

3. Ease of Sharing

Markdown files are fairly hard to share since most browsers do not render them natively well. You often have to add them as attachments to emails or messages.

Markdown files are fairly inconvenient to share because most browsers do not render them well natively, so you often end up attaching them to emails or messages.

As long as you upload the HTML file, you can share the link easily. Your colleagues can open it wherever they wish and easily reference it.

Once an HTML file is uploaded, you can share a link directly. Your colleagues can open it from any device at any time and reference it easily.

The chance of someone actually reading your spec, report, or PR writeup is much higher if it's in HTML.

If your spec, report, or PR writeup is in HTML, people are much more likely to read it carefully.

4. Two-Way Interactions

HTML can also allow you to interact with the document; for example, you might want to ask it to add sliders or knobs to adjust a design or allow you to tweak different options in the algorithm to see what happens. You can also ask it to let you copy these changes into a prompt to paste back into Claude Code.

HTML also lets you interact with the document itself. For example, you can ask Claude to add sliders or knobs so you can adjust a design visually, or tweak algorithm parameters and observe the impact. You can also ask it to add a way to copy those changes into a prompt you can paste back into Claude Code.

When useful, this can allow you to create individual editing environments for the specific problem you're working on.

When used well, this creates dedicated ad hoc editing environments tailored to the exact problem you are solving.

5. Data Ingestion

One of the biggest reasons to use Claude Code to make HTML files instead of Claude.ai or Claude Design is all of the context Claude Code can ingest. For example, when writing this article, I asked Claude Code to read through my code folder and find all the HTML files I've generated, group and categorize them, and then make an HTML file with diagrams representing each type. The diagrams you see in this article are a direct result of that.

One reason we use Claude Code to generate HTML—rather than Claude.ai or Claude Design—is the amount of context Claude Code can ingest. While writing this article, I asked Claude Code to scan my code directory, find every HTML file it had generated, group and categorize them, and then produce an HTML document with diagrams for each category. The diagrams in this article were directly produced through that workflow.

Besides the file system, Claude Code can find additional context using your MCPs (like Slack, Linear, etc.), your web browser (with Claude in Chrome), and your git history.

Beyond the filesystem, Claude Code can also pull context from your MCPs (such as Slack, Linear, etc.), your web browser (via Claude in Chrome), and your git history.

2. Getting Started

One thing worth noting: you don't need to do much to get Claude to generate HTML like this. You can simply prompt it to "make an HTML file" or "make an HTML artifact." The main thing is knowing what you want the artifact to do and how you might use it. Over time, it may make sense to build a skill around recurring patterns, but starting by prompting from scratch is a good way to get a feel for how it works across different use cases.

One important point: you don’t need much to get Claude to generate this kind of HTML. You can simply ask it to “make an HTML file” or “make an HTML artifact.” The key is to know what you want the artifact to do and how you’ll use it. Over time, it may make sense to build a reusable skill around repeated patterns, but starting from scratch prompts is a good way to get a sense of how it works in different use cases.

3. Use Cases

To make this approach more concrete, below are some example use cases where I think using HTML files make more sense than Markdown.

To make this approach more concrete, here are some scenarios where HTML makes more sense than Markdown.

1. Specs, Planning, and Exploration

HTML is a rich canvas for Claude to dive into a problem. When I start working on a problem instead of a simple Markdown plan I expect to make a web of HTML files. For example, I might start with asking Claude Code to brainstorm and create some explorations of different options. I would then ask it to expand more into one, maybe make mockups or examples of the type interfaces. Finally, when I feel good I'll ask it to write an implementation plan. When I'm happy with the plan I'll create a new session and pass in all of these files for it to implement.

HTML is a rich canvas for Claude to explore a problem in depth. When I start a new problem, rather than expecting one simple Markdown plan, I expect a web of linked HTML files. For example, I might first ask Claude Code to brainstorm and generate explorations of different options. Then I ask it to expand on one path, perhaps by creating mockups or examples of interface types. Finally, when the direction is clear, I ask for an implementation plan. Once I’m satisfied with the plan, I open a new session and feed all these files in for execution.

When verifying I'll also ask the verification agent to read in the files and it will have much broader context on what is needed.

For verification, I also ask the verification agent to read those files so it has a much broader context of what needs to be implemented.

Example prompts:

I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches—vary layout, tone, and density—and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making.

I’m not sure which direction to take for the onboarding screen. Generate six distinct approaches with different layout, tone, and information density, and arrange them in a single HTML grid so I can compare them side by side. Clearly label the trade-offs each approach makes.

Create a thorough implementation plan in an HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

Create a thorough implementation plan in an HTML file. Include mockups, show data flow, and add key code snippets I may want to review. Keep the layout clear and easy to read.

Use this for:

• Exploring other ways to implement something in code
• Experimenting with multiple visual designs at once

2. Code Review and Understanding

Code can be difficult to read in a Markdown file, but with HTML, we can render diffs, annotations, flowcharts, and modules. Use HTML to understand code that the agent has written, to review code, or to explain a PR to someone reviewing your code.

Code can be painful to read in a Markdown file. With HTML, we can render diffs, annotations, flowcharts, and module diagrams. Use HTML to understand code written by the agent, perform code review, or explain a PR to reviewers.

Example prompt:

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.

Help me review this PR by creating an HTML artifact. I’m not very familiar with streaming/backpressure logic, so please focus on that. Render the actual diff with inline margin annotations, color-code findings by severity, and include any visuals needed to communicate the concept clearly.

Use this for:

• Creating a PR description
• Reviewing a PR
• Understanding a topic in code

3. Design and 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 out a design in HTML and then write it in your language of choice, be it React, Swift, etc.

Claude Design is built on HTML because HTML is incredibly expressive for design, even if the final product is not rendered in HTML. Claude can sketch a design in HTML first, then convert it to your language of choice, whether that is React, Swift, or something else.

You can also prototype interactions, such as animations, actions, etc. Consider asking Claude to make sliders, knobs, etc. to tune in exactly what you're looking for.

You can also prototype interactions, such as animations and actions. Consider asking Claude to add sliders, knobs, and controls so you can fine-tune the behavior to your exact needs.

Example prompt:

I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create an HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.

I want to prototype a new checkout button: when clicked, it should play an animation and quickly turn purple. Please create an HTML file with several sliders and options so I can test different animation settings, and include a copy button to copy the best-performing parameters.

Use this for:

• Creating design system artifacts
• Adjusting components
• Visualizing component libraries
• Prototyping animations

4. Reports, Research, and Learning

Claude Code is very effective at synthesizing information across multiple data sources and converting it into a report for readability. You can prompt Claude to search your Slack, your codebase, git history, or the internet and use it to generate easy to read reports.

Claude Code is very good at synthesizing information across multiple sources and turning it into readable reports. You can ask it to search Slack, your codebase, git history, or the internet and generate a clear, readable report.

You could assemble this in the form of a long HTML document, an interactive explainer or even a slideshow/deck. Ask Claude to use SVG for diagrams to help visualize it.

You can package this as a long-form HTML document, an interactive explainer, or even a slideshow. Ask Claude to use SVG for diagrams to improve visual clarity.

Example prompt:

I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a "gotchas" section at the bottom. Optimize it for someone reading it once.

I don’t fully understand how our rate limiter works. Please read the relevant code and produce a single-page HTML explainer that includes: a token-bucket flow diagram, 3–4 key code snippets with annotations, and a “gotchas” section at the bottom. Optimize it for a single-pass read.

Use this for:

• Writing feature summaries
• Generating explainers
• Drafting weekly status reports
• Creating incident reports
• Producing SVG illustrations, flowcharts, and technical diagrams

5. Custom Editing Interfaces

Sometimes it's hard to describe what you want purely in a text box. For this use case, I'll often ask Claude to build me a throwaway editor for the exact thing I'm working on: not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data.

Sometimes it’s hard to express a need through a text prompt alone. In these cases, I often ask Claude to build a disposable, purpose-built editor for the specific task at hand: not a product and not a reusable tool, just a single HTML file tailored to that specific dataset.

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 or commit to a file. You stay in the loop, but the loop gets much tighter.

The key is to end with an export mechanism—such as a “Copy as JSON” or “Copy as Prompt” button—so whatever you did in the interface can be converted back into text you can paste into Claude Code or commit to a file. You remain in the loop, but with a much tighter feedback cycle.

Example prompts:

I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a "copy as Markdown" button that exports the final ordering with a one-line rationale per bucket.

I need to reprioritize these 30 Linear tickets. Please create an HTML file with each ticket as a draggable card across four columns: Now / Next / Later / Cut. You can pre-sort them based on your best judgment. Add a “Copy as Markdown” button that exports the final ordering, including a one-line rationale for each bucket.

Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a "copy diff" button that gives me just the changed keys.

Here is our feature flag config. Build a form-based editor for it. Group flags by area, show dependencies among them, and warn me if I enable a flag while one of its prerequisites is turned off. Add a “Copy Diff” button that exports only the keys I changed.

I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button.

I am tuning this system prompt. Build a side-by-side editor with an editable prompt on the left and variable placeholders highlighted, and three sample inputs on the right that live-render the filled template. Add character and token counters and a copy button.

Use this for:

• Reordering, triaging, or bucketing anything
• Editing structured config
• Tuning prompts and templates with live preview
• Curating datasets
• Annotating documents, transcripts, or diffs
• Picking values painful to express in text

FAQ

These are the questions I get asked most often about using HTML with Claude Code, paired with the practical, day-to-day habits I've landed on.

These are the questions I’m asked most often about using HTML with Claude Code, along with the practical habits I’ve settled into in daily work.

Isn’t this a waste of extra tokens?

Q: Isn't it less efficient?

While Markdown often uses fewer tokens, I've found that the added expressiveness of HTML and the much higher likelihood of me reading it means I get overall better output. With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable in the context window.

Markdown usually uses fewer tokens, but I’ve found that HTML’s expressiveness and its higher chance of being read by humans leads to better overall results. With Opus 4.7’s 1M context window, the extra token cost is not noticeable in practice.

When do you still use Markdown?

Q: When do you use Markdown now?

I have honestly stopped using Markdown altogether for almost everything, but I'm probably far on the HTML maximalist side of things.

Honestly, I have almost stopped using Markdown for everything, though I probably lean heavily toward a very HTML-maximal approach.

How do I view generated HTML files?

Q: How do I view the generated HTML file?

I usually open it locally in a browser (you can even ask Claude to open it for you). If I want to share a link, I just upload it to S3.

I usually open it in a local browser (you can even ask Claude to open it for you). If I need to share it, I just upload it to S3 and share the link.

Isn’t generating HTML slower than Markdown?

Q: Doesn't it take longer to generate?

Yes! HTML can take 2-4x longer to generate than Markdown, but in my testing, the output is consistently worth the wait.

Yes. Generating HTML can take two to four times longer than Markdown, but in my experience, the results are consistently worth the extra time.

What about version control?

Q: What about version control?

Honestly, this is one of HTML's biggest pain points. HTML diffs are very messy in version control tools compared to clean Markdown, making code review harder.

Honestly, this is one of HTML’s biggest pain points. HTML diffs can be much noisier than clean Markdown in version control systems, which can make code review harder.

How can HTML replace planning documents?

Q: Is this how you've replaced planning?

I've found that instead of having a single plan, I tend to have a few different HTML files for different parts/stages of the plan. For example, I may make an implementation plan in HTML and then do another file for exploration of UIs, and then finally make an HTML component that lists every design. I tend to keep these files around as references for the future, as well for use in verification.

I’ve found that instead of a single monolithic plan, I usually maintain several HTML files for different parts and stages of planning. For example, I may start with an HTML implementation plan, then create another for UI exploration, and finally an HTML artifact that lists all designs. I keep these files as long-term references and also use them during verification.

How do I make Claude generate aesthetically pleasing pages?

Q: How do I get Claude to generate pages that look good?

Claude's built-in frontend design capabilities already allow it to generate fairly nice HTML pages. But if you want pages to match your company's brand, you can ask Claude to scan your codebase and generate a design system HTML file. Then you can pass that file as reference whenever you need Claude to generate other HTML pages, and it will maintain a consistent style.

Claude’s built-in frontend design capabilities already allow it to generate reasonably good HTML pages. If you want outputs that match your company brand, you can ask Claude to scan your codebase and generate a design-system HTML file. Feed that file back as a reference whenever you need Claude to generate additional pages, and it will keep styling consistent.

*The original author is Thariq Shihipar, engineering lead for Claude Code at Anthropic. The article represents his personal perspective and preferences.*

*This article was written by Thariq Shihipar, engineering lead for Claude Code at Anthropic, and expresses his personal opinions and affinity for using HTML files with Claude Code.*

References

• Using Claude Code: The Unreasonable Effectiveness of HTML (Original)
• Sample HTML File Library
• Thariq Shihipar’s original post on X (Twitter)
• Simon Willison’s interpretation and summary