Markdown vs HTML for Claude Code. Where HTML wins, where markdown still wins, the token-cost gotchas, and the one-line prompt that switches it.
Markdown vs HTML for Claude Code comes down to one rule. Use markdown when the output stays inside the engineering loop. Use HTML when the output goes to a human. Anthropic's own Claude Code team just switched defaults to HTML for the deliverables they ship, and the case is hard to argue with.
On May 9, 2026, Thariq from the Claude Code team at Anthropic published a short piece called Using Claude Code: The Unreasonable Effectiveness of HTML. 48 hours later it had 10.9M views. The argument is one line. Stop telling Claude Code to write markdown. Tell it to write HTML.
That is not a small swap. Markdown has been the default agent output for every shipped LLM product since GPT-3.5. Specs, plans, reviews, audits, code reviews, customer reports, all of it pours out the same way. Headers. Bullets. Tables that break above 30 rows.
I'm Tom. I run AI Architects. I write specs in Claude Code daily and rewrote two of mine this morning using the HTML output style. This is the head-to-head: where each format wins, where markdown still beats HTML, the token-cost gotchas, and the one-line prompt to test it on the next thing you write.
HTML output for Claude Code is a single self-contained .html file with inline CSS, written by Claude in the same way it would otherwise write a markdown doc. You ask Claude Code to write an audit, a plan, a pricing model, or a dashboard, and you append one line to the prompt telling it to output HTML instead of markdown. The file opens in any browser. No build step. No dependencies.
The simplest test is one prompt change. Take the next plan you would normally ask Claude Code to write, and append this:
Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies.
Run it once on real work. Compare the artifact to the markdown version you would have produced. The second one is the deliverable.
Thariq sits on the team that builds Claude Code. He is not an influencer take. He is the person whose default output choice rolls downstream into how Claude Code ships work for the customers paying $20 to $200 a month for it. His open repo of HTML examples has 30 side-by-side artifacts. The GitHub source is public.
His argument is structural. Markdown is a transport format. It moves text between systems cleanly. The reader is almost always a machine, with humans tolerating it as a side effect. HTML is a presentation format. It moves text to a human, with browsers handling layout, navigation, and interaction for free.
When the audience for the artifact is a human, you have been picking the wrong default for two years. Switching is one line in the prompt.
The 10.9M views matter less than who he is. Influencer posts move views. Team posts move defaults. The next round of Claude Code documentation, the next round of skills shipped by Anthropic, the next round of cookbook examples, they will quietly tilt HTML-first. You can stay ahead of that or you can wait for it to catch up.
Nine dimensions, side by side. The pattern is consistent. Markdown wins on machine readability, version control, and chained-agent handoff. HTML wins on everything that touches a human.
| Markdown | HTML | |
|---|---|---|
| Readability over 100 lines | Wall of text. Scroll-only. | Sticky sidebar, collapsible sections, table of contents. |
| Shareability | Paste into Gmail and pray. | One URL. Opens in any browser. Mobile-friendly out of the box. |
| Interactivity | Read-only. | Sliders, toggles, copy-as-prompt buttons, edit-in-place fields. |
| Generation time | 30s for a 1,000-word doc. | 90 to 120s for the same content. |
| Token cost | ~250 tokens per 1,000 words. | ~1,500 tokens per 1,000 words. |
| Version control | Clean diffs. Reviewable in PRs. | Attribute-noise diffs. Unreadable in git. |
| Chained-agent handoff | Parses cleanly into the next agent. | Carries layout the next agent has to strip. |
| Client perception | Looks like a transcript. | Looks like a deliverable. |
| Best use | Engineering plumbing, drafts, short replies. | Anything you would otherwise paste into a Google Doc. |
The honest read of the table: HTML is better at being a finished thing. Markdown is better at being a working thing. The mistake most Claude Code users make is treating the format as a religion. Pick per artifact, not per agent.
Five places where the format swap changes the output quality, not just the look. Each comes with a one-line prompt you can paste straight into Claude Code today.
A markdown audit reads like a checklist. An HTML audit reads like a deliverable. Same content. The client pays for the second one. Prompt: Convert the audit notes at [PATH] into a client-ready single-file HTML deliverable with a branded header, executive summary callout, severity badges per finding, and print-friendly CSS.
A 14-step plan in markdown is a wall. The same plan in HTML can have collapsible phases, a progress bar at the top, and a copy-as-prompt button on every sub-task. The plan stops being a document and starts being a tool. Prompt: Rebuild [PATH/PLAN.md] as a single HTML file with sticky sidebar nav, collapsible phases, and a copy-as-prompt button per sub-task.
8 competitors. 12 attributes each. In markdown that is a table that breaks above the third column. In HTML it is a sortable filterable grid. Prompt: Build a competitor comparison as a single HTML file with a sortable filterable table, a live search box, and coloured badges for pricing tier and target market.
A revenue forecast in markdown is a guess. The same forecast in HTML with input sliders is a model. The client moves the slider and watches year-end revenue change. That is the difference between sending a report and sending decision support. Prompt: Build a pricing calculator as a single self-contained HTML file with sliders for users, AOV, conversion, and churn, and auto-updating outputs for monthly revenue, annual revenue, LTV, and CAC payback.
A markdown weekly report is stale the day it is generated. An HTML dashboard that pulls from MCPs when you open it is live. Prompt: Generate a weekly metrics dashboard as a single HTML file pulling from the Stripe MCP for revenue and churn, the git log for commits, and a local Airtable export for pipeline. Layout: 4 KPI cards on top, transactions table in the middle, commits by author on the bottom.
This is the part Thariq's piece soft-pedals. Markdown is not dead. It is the right default for a specific kind of work, and four cases in particular.
Chained agent workflows. When the output of one agent is the input to another, you want clean structured text. Markdown parses. HTML carries layout the next agent has to throw away. A planning agent that hands a task list to an execution agent should hand markdown bullets.
Anything inside a git repo. HTML diffs are a wall of attribute changes that hide the substance. If the artifact lives in a repo and gets edited weekly, markdown is what lets you actually review what changed. Keep markdown as source of truth, generate HTML on demand, gitignore the rendered output.
Short outputs. A 20-line answer to "what is the syntax for X" does not need a styled HTML page. The format should match the use of the artifact, not the ambition of the prompt.
Inline notes and drafts. When you are still figuring out what you think, markdown gets out of the way. HTML invites you to style your way out of doing the actual work.
Three things to budget for before you swap your defaults. None of them kill the argument. They just stop you defaulting blindly.
Generation time. A markdown plan that takes 30 seconds takes 90 to 120 seconds in HTML. Two to four times slower. On long sessions this stacks. If your loop depends on fast turns, stay in markdown for the loop and convert at the end.
Token cost. A 1,000-word doc costs ~250 input tokens in markdown. In HTML it costs ~1,500. I cut my OpenClaw bill from $600 a month to $25 last quarter, and one of the levers was capping output. The full OpenClaw cost optimization writeup walks through the rest. Defaulting every output to HTML reverses that work for the wrong reasons. Pick per artifact.
Diff noise. HTML attributes destroy git diffs. Keep a markdown source. Render HTML on demand. Gitignore the output.
Take the next plan, audit, or report you would normally ask Claude Code to write in markdown. Append one line to the prompt. Run it once on real work. The artifact you get back is the deliverable. The markdown one was the transcript. After three runs you will pick the right format per artifact automatically.
The rule of thumb after a week of running both on the same pipeline: markdown for short outputs, chained agents, anything in a git repo, anything you will iterate on weekly, anything inside the engineering loop. HTML for anything you send to another human, anything over 100 lines, anything with comparisons or sliders or dashboards, anything you would otherwise paste into a Google Doc. That covers 80% of the calls. The other 20% is judgment.
Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies.
HTML output for Claude Code is a single self-contained .html file with inline CSS, generated by Claude in place of a markdown doc. You append one line to the prompt and Claude returns a file that opens in any browser. No build step, no framework, no dependencies.
No. For agents handing output to other agents, markdown is still better. It parses cleanly, has no layout to strip, and uses 4 to 8 times fewer tokens. HTML is better when the audience for the artifact is a human, not a machine.
Use markdown when the output goes into another agent, lives in a git repo, is under 30 lines, or is still in draft. Markdown wins on diffs, on chained-agent handoff, on generation speed, and on token cost. Save HTML for finished deliverables.
Append one line to your prompt: "Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies." Claude Code reads it as a format instruction and produces an HTML file instead of a markdown doc.
Yes. Roughly 4 to 8 times more. A 1,000-word doc is around 250 tokens in markdown and around 1,500 tokens in HTML. Generation also runs 2 to 4 times slower. Budget for it, and pick per artifact rather than defaulting everything to HTML.
Claude Code writes the file to disk. You open it in any browser to render. There is no in-terminal render. The file is portable, so you can send it as a single attachment or host it as a static page.
Thariq's public repo has 30 side-by-side examples at thariqs.github.io/html-effectiveness. The GitHub source is at github.com/thariqs/html-effectiveness. Worth bookmarking before you write your next deliverable.
The real lesson is not "switch to HTML." The real lesson is that format is a lever. Most Claude Code users pick the default and never touch it. Architects pick the format that fits the use of the artifact and ship the right thing for the audience on the other end.
If you are running Claude Code on real client work and you have never written a custom output prompt, that is the gap. Close it this week. The free Claude Code Blueprint walks through 60 minutes of guided builds including the output-format prompts I use on every deliverable. For the deeper version, the 30 Day Claude Code Challenge is the cohort that ships four real builds end to end.
Build something. I will be there for the parts that break.
Five interactive lessons. Install Claude Code, build your first automation, and deploy it live on the internet — all in under an hour. Free, no coding required.
Grab the Blueprint →