Stop Writing Markdown — Use HTML with Claude Code

Markdown has been the default communication format between agents and humans in the AI coding space. It’s simple, portable, supports basic rich text, and is easy to edit by hand. Claude even learned to draw ASCII diagrams inside Markdown — surprisingly passable ones.

But Thariq, a core engineer on the Anthropic Claude Code team, recently published a post on X declaring he’s almost completely stopped using Markdown. Not because it’s bad, but because as agents grow more capable, Markdown’s simplicity becomes a ceiling. He candidly admits: he doesn’t read Markdown files over a hundred lines. And he rarely edits these files manually anymore — when changes are needed, Claude does them. That undermines Markdown’s biggest selling point: human editability.

His replacement is HTML, not as a fallback, but as the primary output format. And he’s not alone — more people inside the Claude Code team are doing the same.

Why HTML

Thariq lays out six reasons, and they all converge on the same point: HTML’s expressive power operates in a completely different league from Markdown.

Information density. HTML carries vastly more information. Beyond basic document structure (headings, bold), it handles tabular data via <table>, design through CSS, illustrations via SVG, code snippets with <script> tags, workflow diagrams using SVG geometry, interactive elements with JavaScript, and spatial data via absolute positioning and canvas. There’s almost nothing a language model can express that HTML can’t represent. When you constrain the model to Markdown, it resorts to awkward workarounds — ASCII diagrams, Unicode characters to approximate colors. The result is a compromise, not communication.

Visual clarity and readability. This is the most practical pain point. As Claude tackles more complex tasks, its specs and plans grow longer. In practice, nobody on the team reads Markdown beyond 100 lines. HTML documents are dramatically more readable — Claude can organize content into tabbed sections, embed illustrations as visual anchors, add navigation links, and even make the layout responsive for different devices.

Shareability. Markdown files are hard to share because most browsers don’t render them natively. You end up attaching .md files to emails or dropping them into chat messages. With HTML, upload to S3 or any static host and share a link. Colleagues open it anywhere, reference it anytime, and actually read it. A spec, report, or PR description has a much higher probability of being read as HTML than as Markdown.

Two-way interaction. HTML lets you interact with the document. Thariq regularly asks Claude to add sliders or knobs to adjust design parameters in real time, toggle between algorithmic options to compare behavior, or include a button that copies the UI state back as a prompt for Claude Code. None of this is possible in plain-text Markdown.

Data ingestion. Why not just use Claude.ai or Claude Design to generate HTML? Thariq’s answer is direct: Claude Code can ingest vastly more context. File systems, MCP servers (Slack, Linear, etc.), web browsers through Claude in Chrome, Git history — all feeding into one artifact. When writing the original article, he asked Claude Code to scan his code folder, find every HTML file he’d ever generated, group them by type, and produce a single categorized gallery. That depth of context isn’t accessible from other interfaces.

Fun. This last one sounds whimsical but Thariq makes a point of including it: working in HTML is simply more fun. It makes you feel more engaged, more like you’re building something rather than writing notes. That alone is reason enough.

How to Start

Thariq’s advice is unexpectedly simple: no skills to build, no config files to write. Just tell Claude “make me an HTML file.” The key is knowing what you want this artifact to do and how you’ll use it. Over time you might develop patterns, but start with zero-shot prompts and explore different scenarios.

He admits he worried people would immediately build an /html skill after reading the article — it might help, but the preparation isn’t the point. Let the specific use case drive the format, not the other way around.

Specific Usage Patterns

To make things concrete, Thariq built a collection of HTML artifacts across different use cases, available at thariqs.github.io/html-effectiveness. He identifies five patterns.

Spec, planning, and exploration. HTML is a canvas for deep exploration. Instead of writing a Markdown plan, he now generates a set of HTML files: brainstorm first, explore different options, then dive deep into one with mockups and code snippets. Once the plan solidifies, he opens a new session and feeds all those files in for implementation. A typical prompt: “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.”

Code review and understanding. Code is notoriously hard to read in Markdown. HTML renders diffs with inline annotations, flowcharts, and module relationship diagrams. Thariq finds this more readable than GitHub’s default diff view and now attaches an HTML explainer to every PR. For reviewers unfamiliar with the codebase: “Help me review this PR by creating an HTML artifact that describes it — render the actual diff with inline margin annotations, color-code findings by severity, and whatever else might be needed to convey the concept well.”

Design and prototyping. Claude Design itself is HTML-based, because HTML is extraordinarily powerful for design expression — even when the target platform isn’t HTML. Claude can sketch in HTML first, then port to React, Swift, or any other framework. Add sliders and controls to fine-tune parameters, then copy the result.

Reports, research, and learning. Claude Code excels at synthesizing information from multiple sources — Slack, codebase, Git history, the web — into readable reports. The output can be a long-form HTML document, an interactive explainer, or even a slide deck. When Thariq wrote his prompt caching thread, he had Claude read every Git commit related to prompt caching, then prepare a deep-research HTML file for him to study. Try: “I don’t understand how our rate limiter 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.”

One-shot editors. Some things are hard to describe with text alone. Thariq’s solution: have Claude build a throwaway editor designed for exactly this one task — not a product, not a reusable tool. Reorder 30 tickets, edit feature flags, tune a system prompt with live preview, annotate a dataset line by line. The critical rule: always end with an export button. “Copy as JSON” or “Copy as prompt” — convert what you did in the UI back into text for the next chat turn.

The real shift isn’t technical. It’s feeling like you’re in the loop again, instead of watching the agent take detours you never approved.