Our team runs fast. Everyone uses AI — for code review, architecture decisions, issue triage, sprint planning. The individual work is solid. The outputs are good.
The problem shows up in the meeting.
Someone opens a PR and shares the AI-generated action plan in the standup. It is a .md file, 200+ lines, logically structured, accurate. The engineer who ran it knows exactly what is in it.
The two people looking at it for the first time are scrolling, skimming, trying to locate what matters while the conversation moves on.
Our lead eventually just asked:
“Can you highlight what’s actually blocking us right now?”
That was not a knowledge gap. Everyone in the room was technical. It was not a preparation gap either — the work had been done well.
The gap was between the person who had been living in that context and everyone else trying to enter it in 90 seconds from a flat text file.
That is a format problem.
And it compounds every time AI-generated work crosses from one person’s context into a shared one.
The Post That Reframed It
On May 8, 2026, Thariq Shihipar, an engineer on the Claude Code team at Anthropic, posted nine words on X:
“HTML is the new markdown. I’ve stopped writing markdown files for almost everything and switched to using Claude Code to generate HTML for me. This is why.”
The post linked to a companion site: 20 self-contained .html files, each one an agent-generated artifact covering a different category of engineering work.
No build step.
No framework.
Just a file you open in a browser.
The line that stopped us was from Thariq’s framing of the Code Review category:
“Diffs and call-graphs are spatial information; markdown flattens them.”
That was the exact problem we’d been circling for weeks without naming it. Our action plans weren’t hard to read because they were long.
They were hard to read because the information inside them was spatial — priority relationships, status changes, size deltas, dependency chains — and we were delivering it as a flat sequence of text.
Simon Willison, whose writing on developer tooling is widely followed, read the piece the same day and wrote that it caused him to reconsider his three-year default of asking for everything in Markdown.(3)
His note: Markdown won because of constraints — the 8,192-token GPT-4 era, where every character counted. Those constraints are largely gone. The reasoning that locked in the default hasn’t been re-examined.
That evening, we ran our own action plan through Claude with one change:
“Output this as a standalone HTML file with priority-coded sections, status badges, and a visual summary header.”
Thirty minutes of iteration.
The document we’d been failing to share effectively for weeks was suddenly something a new set of eyes could navigate in under a minute.
Why This Works: Source for Machines, Interface for People
Before going further, the actual rule is worth stating clearly, because the headline “HTML is the new markdown” gets misread.
This isn’t about replacing Markdown everywhere.
README files, commit notes, audit logs, agent-to-agent context passing — Markdown stays. It’s compact, diffable, searchable, and parseable without a browser. Those are real advantages that don’t disappear.
The shift is narrower: when AI-generated work reaches a human who needs to review, navigate, and act on it, Markdown hands the translation cost to the reader. HTML absorbs it into the document.
Karpathy replied to Thariq’s post with a practical note:
“This works really well btw — at the end of your query ask your LLM to ‘structure your response as HTML’, then view the generated file in your browser.”
He added the underlying reason: roughly a third of the human brain is dedicated to visual processing — the 10-lane superhighway of information into the brain. Audio is the preferred input to AI. Vision is the preferred output from it.
That is why the format question matters beyond aesthetics. If AI output is increasingly something people have to review, navigate, and act on quickly, then the container is no longer a neutral wrapper.
A February 2026 Harvard Business Review study tracked 200 employees at a U.S. tech company over eight months and found that AI adoption intensified work rather than reducing it — 83% reported it increased their workload. (5)
The study doesn’t prove a format problem by itself. What it describes is the broader environment in which format problems become expensive: workers moving faster, taking on broader scope, with less time per handoff.
In that environment, a document format that requires translation before action isn’t a minor inconvenience. It’s a recurring tax.
The 20 Examples: A Map Worth Keeping
So what does a better container look like in practice?
Thariq’s companion site at thariqs.github.io/html-effectiveness is worth opening in a separate tab.
It’s not a gallery — it’s a structured argument across 9 categories, each one showing where Markdown flattens information that HTML can spatialize.
Here’s the full map for reference. Skim it — it’s a map, not a reading list. The three categories that actually changed our workflow are below the table.
| # | Category | What HTML replaces | Examples |
|---|
| 01 | Exploration & Planning | Sequential walls of text you try to hold in memory | Three code approaches side-by-side · Visual design directions rendered live · Implementation plan with timeline and risk table |
| 02 | Code Review | Flat diff output, call-graph prose | Annotated PR with margin notes and severity tags · PR writeup with file-by-file tour · Module map as boxes and arrows |
| 03 | Design | Token/component descriptions | Living design system with swatches · Component variants on a single sheet |
| 04 | Prototyping | Prose descriptions of motion and interaction | Animation sandbox with easing sliders · Clickable flow across four screens |
| 05 | Diagrams | Text-based flowcharts | SVG figure sheet · Annotated flowchart — click any step to see timings and failure paths |
| 06 | Decks | PowerPoint export, PDF | Arrow-key slide deck — one HTML file, no build step |
| 07 | Research & Learning | Linear explainer dumps | Feature explainer with collapsible steps and tabbed config · Concept explainer with live interactive ring |
| 08 | Reports | Weekly status emails, post-mortem docs | Weekly status with a small chart · Incident timeline with minute-by-minute breakdown |
| 09 | Custom Editors | Text-box instructions for spatial decisions | Ticket triage board · Feature flag editor with dependency warnings · Prompt tuner with live re-render |
Code Review (02).
The annotated PR demo made the problem undeniable. Our action plans were spatial data — P0 vs P1 vs P2, open vs fixed, size deltas — delivered as a flat sequence. Moving to HTML turned priority into visual hierarchy, status into badges, and growth from 163 to 212 lines into an amber callout. The reviewer’s eye went to the right place without being guided there by more text.
Decks (06).
A handful of <section> tags and a little JavaScript becomes a slide deck you can arrow-key through in a meeting. No Keynote. No export. The charts can stay live, the regional breakdown can be filterable, and the presenter stops defending the format and starts defending the idea.
Custom Editors (09).
This is the category most people miss. It isn’t about pretty reports. It’s about asking for a throwaway interface for one specific decision — triaging tickets, toggling feature flags, tuning a prompt template — then exporting the result as structured Markdown for the next agent call. The loop gets tighter.
How We Applied It in Practice
The next step was turning the rule into a workflow.
We didn’t replace Markdown. We added an HTML render layer on top of it.
Every agent run now produces two files. The raw .md stays for version control, diffs, and agent context — passing HTML between agents adds token cost without value. The HTML is what the team opens.
The status bar at the top shows Open / Fixed / Partial counts at a glance. P0 items have a red left border and a pulse. Fixed items are muted. A function that grew from 163 to 212 lines shows the delta in an amber callout — visible without reading the note. The filter bar lets anyone drill to just the P0 items in one click.
Below is the representative example we use. Content has been generalized — no internal identifiers — but the structure, priority system, and status logic are exactly what’s in production.
PR Action Plan Dashboard
Same information. Different container.
One standup dropped from 25 minutes to 12. The questions changed from “wait, which ones are actually blocking?” to “who’s taking P0–1a?”
Beyond the PR: Every Document That Has to Survive a Room
The dev PR use case is where we started. It’s not where this ends.
Think about the last time you sat through a presentation built in PowerPoint. Someone had spent hours on slides, exported a PDF, shared it over email. Half the room opened it on their phones and couldn’t read the charts. The presenter spent the first three minutes explaining the color coding. Someone asked about a specific number and the answer was “I’ll have to check the spreadsheet.”
That’s the same problem. Spatial information delivered as a fixed object, forcing everyone in the room to translate before they can respond.
A quarterly review as a single HTML file looks different. The slides are still there — arrow-key navigation, no build step. But the charts are live. Each person hovers over the number they care about.
The regional breakdown is filterable. A response field at the bottom lets stakeholders flag a concern or submit a priority vote before leaving the page. That input comes back as structured data the next agent call can act on. The meeting doesn’t end with action items in someone’s notebook. It ends with a file.
This is what “sending a document” becomes when the format is HTML. A PDF is a fixed object. An HTML file is an environment. The person receiving it navigates it on their own terms — without matching your reading pace, your zoom level, or your familiarity with the data. And if you’ve built in the export button, what they do inside it comes back to you.
The pattern holds wherever AI-generated work has to cross a context boundary. A business proposal needing sign-off from people who weren’t in the original conversation. A research summary that has to land with someone from a different discipline.
A vendor comparison that three stakeholders need to filter differently. In each case, the question is the same: does the format help the next person enter the work, or does it make them translate it first?
The Tradeoff, Honestly
Every format shift moves cost somewhere. HTML is no exception.
HTML costs more to generate. For a document the size of our action plan, the HTML version runs approximately 4,200 tokens. The equivalent Markdown is around 1,150. That’s a 3.6× multiplier on output tokens.
At Claude Sonnet pricing as of May 2026, the delta is roughly $0.009 per document. At 100 documents per day, that’s about $0.90 extra per day — real, but not significant for most teams.
The more useful frame: one missed P0 finding costs more than a month of that overhead. The token cost is the price of a format that gets reviewed properly instead of skimmed and hoped at.
But token cost is only the first tradeoff.
Three rules keep the format honest.
Rule 1: HTML is for human review, not machine handoff.
HTML is not a good input for agent-to-agent pipelines. Keep Markdown for source, diffs, archives, and machine context. HTML earns its cost only at the human review surface.
Rule 2: visual authority is not factual authority.
A red P0 badge doesn’t mean the agent got the priority right. A well-structured HTML artifact can make a wrong AI output look more credible than a flat Markdown file would. Faster comprehension helps — it doesn’t replace judgment. The render layer should make review faster, not make the model more trusted.
Rule 3: interactivity needs a safety contract.
A useful HTML artifact should be self-contained, with no remote scripts, so it works offline and doesn’t phone home. It should use text labels alongside color and hover states, so it still works for color-blind readers and keyboard-only users. And if it re-enters an agent loop, it should run sandboxed, without external network access.
None of these are hard to ask for in the prompt. They’re worth adding to your template.
The Prompt Change
You do not need new tooling. One line at the end of your existing prompt.
Instead of:
“Generate a PR action plan covering all open issues by priority.”
Try:
“Generate a PR action plan covering all open issues by priority. Output as a standalone HTML file: color-coded priority badges (P0=red, P1=amber, P2=yellow), status indicators (OPEN/FIXED/PARTIAL), delta callouts for size changes, and a summary header with open and fixed counts.”
For code review, Thariq’s own prompt is worth borrowing directly:
“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.”
The harder shift isn’t the prompt. It’s recognizing that the format of AI output is a design decision. We used Markdown for three years because that’s what the GPT-4 era trained us to expect. The models have moved. The context windows have moved. The use cases have moved.
The next bottleneck isn’t what the agent can generate. It’s whether the next person can enter it fast enough to act.
References
- Thariq Shihipar, “The Unreasonable Effectiveness of HTML” — original X post, May 8, 2026
- Companion examples site — 20 self-contained HTML artifacts across 9 categories
- Simon Willison, link post and notes — May 8, 2026
- Andrej Karpathy, reply to Thariq’s post — visual processing argument
- Ranganathan & Ye, “AI Doesn’t Reduce Work, It Intensifies It” — Harvard Business Review, February 2026