On May 9, Thariq from the Claude Code team published a piece arguing HTML beats markdown for plans, audits, reports, and reviews. 10.9M views in 48 hours. Here is the head-to-head: where HTML wins, where markdown still wins, the gotchas, and 5 prompts to test it on real work.
On May 9, 2026, Thariq (@trq212) 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. You scroll. You ctrl-F. You forget where you were.
Thariq is from the team that builds Claude Code. He is now switching default output to HTML for the work he ships internally. That matters more than another influencer take.
I have spent the last week running both formats side by side on real client work. Audits, plans, dashboards, reviews. Here is the head-to-head, the gotchas, and 5 prompts you can paste into Claude Code today to test it on your own pipeline.
[CTA-BLUEPRINT]
The honest read of the table: HTML is better at being a finished thing. Markdown is better at being a working thing.
Five places I have seen the format swap change the output quality, not just the look. Each comes with a 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 without question. They quibble on the first one.
Convert the audit notes at [PATH/TO/AUDIT.md] into a client-ready HTML deliverable.
Requirements:
- Branded header with [COMPANY NAME] and date
- Executive summary in a callout box at the top
- Each finding gets its own section with a severity badge (high, medium, low)
- Recommendations section at the bottom in priority order
- Footer with my contact details
- Inline CSS, single file, opens in any browser
- Print-friendly so it exports cleanly to PDFA 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.
Take the plan at [PATH/TO/PLAN.md] and rebuild it as a single self-contained HTML file.
Requirements:
- Sticky sidebar with anchored section nav
- Collapsible sub-sections per phase
- A "copy as prompt" button on every sub-task that copies the full sub-task to clipboard
- Print-friendly CSS
- Single file, inline styles, no external dependencies
Output to [PATH/TO/PLAN.html].8 competitors. 12 attributes each. In markdown that is a table that breaks on mobile and is unreadable after the third column. In HTML it is a sortable filterable grid.
Build a competitor comparison as a single HTML file from [PATH/TO/COMPETITORS.md].
Layout:
- Sortable, filterable table with each competitor as a row and attributes as columns
- A search box that filters rows live
- Coloured badges for categorical fields (pricing tier, target market, etc.)
- Vanilla JS, no frameworks, single file
Output to [PATH/TO/COMPETITORS.html].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.
Build an HTML pricing calculator for [PRODUCT] as a single self-contained file.
Inputs (sliders):
- Monthly active users (100 to 10,000)
- Average order value ($10 to $500)
- Conversion rate (1% to 10%)
- Churn rate (1% to 20%)
Outputs (auto-update on slider change):
- Monthly revenue
- Annual revenue
- LTV
- CAC payback (assume $50 CAC)
Vanilla JS. No frameworks. Clean editorial style.A markdown weekly report is stale the day it is generated. An HTML dashboard that pulls from MCPs when you open it is live.
Generate a weekly metrics dashboard as a single self-contained HTML file.
Pull from:
- Stripe MCP for revenue, new customers, churn
- The git log for commits this week
- The local Airtable export at [PATH] for sales pipeline
Layout:
- Top: 4 KPI cards (revenue, new customers, churn rate, commits)
- Middle: sortable table of all transactions this week
- Bottom: git commit messages grouped by author
Output to [PATH/TO/WEEK-X.html].Run one of these on a real piece of work this week. Compare the artifact to the markdown version you would have produced. The first one feels slow. The second one does not.
For 30 more examples, Thariq published an open repo of HTML artifacts at thariqs.github.io/html-effectiveness. The source is on GitHub at github.com/thariqs/html-effectiveness. Worth bookmarking.
This is the part Thariq's piece soft-pedals. Markdown is not dead. It is the right default for a specific kind of work.
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. Thariq calls this out. 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. The fix when you want both: 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.
Generation time. A markdown plan that takes 30 seconds takes 90 to 120 seconds in HTML. 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 optimised my OpenClaw bill from $600 a month to $25 last quarter. One of the levers was capping output. Defaulting every output to HTML reverses that work for the wrong reasons.
Diff noise. Keep a markdown source. Render HTML on demand. Gitignore the output.
None of these kill the argument. They just stop you defaulting blindly.
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 rule covers about 80% of the calls. The other 20% is judgment.
The simplest test is one prompt change. Take the next plan or audit you would normally ask Claude Code to write in markdown. Append this to the prompt:
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. The second one is the deliverable.
Thariq's piece is the highest-signal Claude Code post of May. It moved 10.9M views in 48 hours because it touched something every Claude Code user has been quietly frustrated by. Markdown was never the right output for half the work we use it for.
The real lesson is not "switch to HTML."
The real lesson is that format is a lever. Most people 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.
If you want a structured way to do that, the Claude Code Blueprint walks through 60 minutes of guided builds inside Claude Code, including the output-format prompts I use on every client deliverable. Free.
No. Format is a lever, not a default. Use HTML for finished deliverables a human will read. Use Markdown for short outputs, drafts, chained-agent handoffs, and anything that lives inside a git repo.
Yes. A 1,000-word doc costs around 250 input tokens in Markdown and around 1,500 in HTML — roughly 4 to 8x more. Generation time is 2 to 4x longer. Budget for it if you are running long sessions or chained agents.
For chained agent handoffs (clean parsing), inline drafts, short answers under 20 lines, and anything that lives in a git repo where diffs matter. Markdown's whole job is to get out of the way while you work.
Append a single prompt instruction: "Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies." Add specific structural requirements (badges, sliders, sortable tables) per artifact.
The phrase is from Thariq at Anthropic's Claude Code team. The thesis: Markdown is fine for the loop, but the final artifact a human reads (audit, plan, dashboard, deliverable) is meaningfully better as HTML because the model can ship layout, interactivity, and styling in one self-contained file.
The format-as-output argument applies to any model that can output structured text and HTML — GPT-5.5, Gemini 3, Claude. The reason this lands inside Claude Code specifically is that the artifact is local: you can save the file, open it in a browser, and ship it. Web chat interfaces add friction the local CLI doesn't have.
Yes. The cleanest pattern is a Skill that takes any Markdown source file and emits a styled HTML deliverable. See the Claude Code Skills guide for how to wrap a recurring output transform into a one-shot trigger.
If this guide was useful, these go deeper on adjacent topics:
Primary sources referenced in this guide:
[CTA-CHALLENGE]
Build something. I will be there for the parts that break.
---
_Originally referenced: Thariq's open repo of HTML examples and the GitHub source. @trq212 on X. Published May 9, 2026. 10.9M views as of May 12._
Not by default. Format is a lever, not a religion. Use HTML for finished deliverables a human will read: audits, plans, dashboards, pricing models. Use markdown for short outputs, drafts, chained-agent handoffs, and anything that lives in a git repo. The decision rule covers about 80% of the calls. The other 20% is judgment.
Yes, significantly. A 1,000-word doc costs around 250 input tokens in markdown and around 1,500 in HTML, roughly 4 to 8x more. Generation time is 2 to 4x longer (90 to 120 seconds vs 30 seconds for the same content). I optimised my OpenClaw bill from $600 a month to $25 last quarter by capping output. Defaulting to HTML reverses that work for the wrong reasons.
Chained agent handoffs where the output of one agent feeds another. Anything inside a git repo where diffs matter (HTML diffs are walls of attribute noise). Short answers under 20 lines. Inline notes and drafts where you are still figuring out what you think. Markdown's whole job is to get out of the way while you work.
Append one prompt instruction: "Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies." Add specific requirements per artifact (severity badges, sortable tables, input sliders). Run it once on real work and compare the artifact to the markdown version you would have produced.
Thariq from the Claude Code team at Anthropic published a piece on May 9, 2026 arguing HTML beats markdown for finished deliverables. 10.9M views in 48 hours. The thesis: markdown is fine for the loop, but the final artifact a human reads (audit, plan, dashboard) is meaningfully better as HTML because the model can ship layout, interactivity, and styling in one self-contained file.
Five places I have seen the format swap change output quality, not just look. Client audits with severity badges and an executive summary. Plans with collapsible phases and copy-as-prompt buttons. Competitor research as sortable, filterable grids. Pricing models with input sliders the client actually moves. Weekly dashboards that pull live data from MCP servers when you open the file.
Keep markdown as the source of truth, generate HTML on demand, gitignore the rendered output. HTML diffs hide substance behind attribute noise. This pattern gives you both clean reviewable diffs in PRs and a styled deliverable when you need to send the file to a human.
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 →