HTML Is the New Markdown? Output vs. Storage
Two of the loudest format arguments in AI engineering right now point in opposite directions. One says an agent's output should be a self-contained HTML file, not a markdown report. The other says your agent's knowledge base should be plain markdown, not a proprietary store. Both are correct, and the reason they do not contradict each other is the most useful thing you can learn about formats this year.
The HTML case has good sponsorship. Thariq Shihipar, an engineer on Anthropic's Claude Code team, published a thread and gallery under the line "HTML is the new markdown" and largely stopped writing markdown files for agent output. Andrej Karpathy independently endorsed asking models to render results as HTML and opening them in a browser. And at AI Engineer, James Russo of HeyGen took the idea to its logical extreme: HTML as the authoring format for video.
TL;DR — "HTML is the new markdown" is a claim about output, not about storage. Models write HTML, CSS, and JavaScript better than any format you could design, because those languages dominate their training data — so agent-generated artifacts meant for a human to read or explore should be self-contained HTML. But the durable layer underneath — specs, decisions, runbooks, agent memory — should stay markdown: cheaper in tokens, readable as raw source, diffable, and portable across every model and tool. Store markdown, render HTML. That is exactly the split MDflow is built on. Start free.
What "HTML is the new Markdown" actually claims
The claim is that a long agent output in markdown is a report, and the same content in HTML is an interface — and interfaces get used while reports get abandoned.
Shihipar's argument, made in detail on Lenny's podcast and in a gallery of twenty self-contained HTML artifacts generated by Claude Code, is behavioural rather than aesthetic. Once context windows grew and agent plans started running to thousands of lines, markdown hit a ceiling: past a hundred lines it is a wall of text you skim once. The same content as a single HTML file can carry tabs, collapsible sections, a responsive layout, SVG diagrams, filters, sliders, and buttons — and it opens in any browser with no toolchain.
Two of his examples are worth stealing outright:
- A plan review rendered as an interactive page, where each section can be edited or approved in place instead of read top to bottom.
- A living design system kept as an HTML file inside the repo, which is simultaneously the human reference and the machine-readable spec the agent codes against — no Figma round-trip.
Karpathy's framing is more fundamental: vision is a ten-lane highway into the brain, and text is a footpath. Under that view HTML is not the destination either, just the best interface format currently cheap to generate.
The counter-case, argued most carefully by Theo in an adversarial review of the thesis, concedes the main point but names the real costs: HTML diffs are genuinely harder to read than markdown diffs, the attention advantage decays as HTML artifacts stop being novel, and the more responsive the artifact, the more tokens it burns. Every one of those objections is about keeping the file, not about reading it — which is the seam this whole debate runs along.
The deeper principle: let models speak their native language
The reason HTML works is not that HTML is a good language. It is that HTML is the language the model already speaks.
HeyGen's talk is the cleanest demonstration, because their problem had nothing to do with documents. They needed agents to compose video — avatar, B-roll, captions, animation, music — and they spent over a year trying formats. Their axes were quality of output against agent-friendliness:
| Approach | Why it fell short |
|---|---|
| After Effects / Premiere | Gold-standard output, but a copilot at best — agents cannot author in it |
| Lottie / Rive (JSON, custom XML) | Decent output, but not a native format, and hard to edit or control |
| Remotion (React) | Genuinely good, but they had to teach the framework, which crowded out creativity |
| Plain HTML + CSS + JS | Models gravitated there unprompted once given only the target output |
As Russo put it, forcing a model into a bespoke DSL is like asking Shakespeare to write a poem in a language he does not speak — you can supply examples, but you will not get his best work. Their design partner was deliberately a small model: if the smallest model could author correct compositions in the format, larger ones certainly would, and the format would keep improving for free as models improved. The surprise was that every wrapper they tried made things worse. The thinnest wrapper won — plain HTML plus a few data- attributes for timing.
The payoff is compounding. Because the composition is a web page, anything the browser can render is now in scope: SVG, Three.js, charts, shaders, WebGL, Lottie. HeyGen's renderer freezes the browser clock and seeks frame by frame, waiting for every asset before screenshotting, so an async medium becomes deterministic MP4. Hyperframes is Apache-2.0 open source and now sits at roughly 38k GitHub stars; on stage Russo reported over 1.3 million videos rendered by open-source users in 90 days.
The generalisable lesson has nothing to do with video: when you are tempted to design a format for your agent, check first whether the model already knows one. The skill you write should teach taste and domain judgement — what makes a good video, a good plan, a good report — not syntax the model would have known for free.
Where HTML wins and where Markdown wins
Pick the format by the artifact's lifetime, not by its content.
| Dimension | HTML | Markdown |
|---|---|---|
| Human reading and exploration | Excellent — layout, tabs, charts, interaction | Adequate up to ~100 lines |
| Model authoring quality | Native, no teaching required | Native, no teaching required |
| Token cost to read back | High — markup, styles, scripts | Low — nearly all signal |
| Diffs and review | Noisy, hard to review | Line-level, reviewable by humans and agents |
| Portability across tools | Needs a browser to be useful | Renders everywhere, readable as raw source |
| Longevity | Styling and scripts rot | Stable for decades |
For developers, this resolves into a workflow rather than a preference. The plan an agent hands you for review should be HTML — you will actually engage with it. The decision that comes out of that review should be committed as markdown, because in six months you will want to know what changed and why, and git diff has to be legible. Treating output format as a first-class lever is the real insight; treating one format as universally superior is how you end up with a repository full of unreviewable artifacts.
For AI agents, the asymmetry is sharper. An agent reading its own knowledge base pays for every token of markup it did not need, and gets no benefit from styling it cannot see. Worse, a knowledge layer stored as HTML is measurably harder for the next tool to parse — and the next tool is the whole point of an open substrate. Markdown is the format every model family handles natively as raw text, which makes it the cheapest interchange layer between your knowledge and a model you have not chosen yet. That argument runs in parallel with the case for model-agnostic architecture: the substrate should outlive whatever sits on top of it.
Which applications benefit most
- Coding agents and plan review — plans, diffs, and architecture proposals rendered as interactive HTML, with the resulting decisions written back as markdown.
- Internal reporting and status updates — a weekly HTML page is read; a weekly markdown file is archived unread.
- Data and analytics workflows — a filterable table with an SVG chart beats a markdown table nobody scrolls.
- Design systems and specs — one HTML file that is both the human reference and the machine-readable source the agent builds against.
- Generative media — the HeyGen case: video, motion graphics, and anything else the browser can already render.
- Knowledge bases and agent memory — the counter-case, and the one that matters most long-term: markdown, always, because these documents are read far more often than they are looked at.
How MDflow fits
MDflow is the markdown half of this split — the durable layer your agents read from and write back to, with rendering as a view rather than the storage format.
What already lines up today
Markdown-native storage, HTML on demand. Documents are stored as plain markdown with no proprietary wrapper. The rendered preview, the shared reader, and the print-ready PDF flow are all renderings of that source — you get the HTML view when a human needs one, and the file on disk stays diffable text. A whole workspace can be exported as a self-contained markdown archive that opens in Obsidian, VS Code, or GitHub without us.
Raw .md twins for agents. Every shared document — and every post on this blog, including /blog/html-is-the-new-markdown.md — has a raw markdown twin any model, script, or CI job can fetch. That is the low-token path into your content; the styled page is for people.
Open protocols, not a format lock. MDflow exposes a remote MCP server (OAuth sign-in for Claude and the ChatGPT app, Personal Access Tokens for Cursor, Codex, and Claude Code), a plain HTTP API with an OpenAPI spec, a VS Code extension, an n8n node, and a web clipper that saves pages as markdown. Agents read and write the same documents through whichever interface they already have.
Retrieval that costs almost nothing. Every folder carries a description stating what its documents are for, and mdflow_get_context ranks those descriptions above folder names and titles — retrieval without a vector database. Combined with markdown's low token weight, an agent answers from three relevant documents instead of thirty plausible ones.
Agents write back, reviewably. MCP write tools are real, so an agent that reaches a decision can record it in the workspace rather than lose it at session end. Version history records every change with an actor, sharing and collections scope what each person or agent can see, and client-side encryption covers what should never be readable by anything but you.
Where we are headed
Direction, not a dated commitment: serving a whole collection to an agent as one cross-linked bundle, so a spec, its decision log, and its glossary arrive together; richer typed frontmatter so documents carry status, owner, and freshness as signals an agent can weigh; and tighter review round-trips for agent-proposed edits before they land.
The bottom line
The format debate looks like a fight and is actually a division of labour. HTML is the new markdown for output — agents write it natively, browsers render it everywhere, and an artifact someone interacts with beats a report they skim. The principle behind that result is bigger than HTML: do not invent a format your model has to be taught when it already speaks one fluently.
But the same principle is why the layer underneath should not move. Markdown is still markdown for storage — the cheapest thing to read into a context window, the only thing you can review line by line, and the one format every model already understands as raw text. Store markdown, render HTML, and let the render be disposable.
Start free · Connect an AI agent · Read the API docs
Frequently asked questions
What does "HTML is the new Markdown" mean?
It is the argument, popularised by Thariq Shihipar of Anthropic's Claude Code team, that when an AI agent produces a long report, plan, or analysis, a single self-contained HTML file serves it better than a markdown file. HTML gives you layout, tabs, collapsible sections, SVG diagrams, filters, and interactive controls, so the output becomes an interface someone actually uses rather than a wall of text that gets skimmed once and abandoned.
Is HTML better than Markdown for AI agents?
For presentation, usually yes. For storage, usually no. HTML wins when a human has to read, explore, or interact with the result — dashboards, plans, design systems, status updates, even video compositions. Markdown wins as the durable substrate: it is cheaper in tokens, readable as raw source by every model, diffable line by line in version control, and renderable anywhere. The two are not competitors; markdown is the source of truth and HTML is one of its renderings.
Why do LLMs write HTML so well?
Because HTML, CSS, and JavaScript are effectively the native languages of large language models. A large share of pre-training data is scraped web pages, so models have seen billions of examples of these three languages and comparatively few examples of your custom JSON schema or domain-specific language. Teams that switched from bespoke formats to plain HTML consistently report better output with smaller models and shorter system prompts, because they stopped teaching the model a second language.
Should I store my notes and agent memory as HTML or Markdown?
Markdown. Storage formats are judged on longevity, diffability, token cost, and portability, and HTML loses on all four. HTML diffs are noticeably harder to review than markdown diffs, HTML costs more tokens to read into a context window, and a document wrapped in styling is harder for the next tool to parse. Store markdown, then render to HTML on demand when a human needs an interface.
What is the practical rule for choosing a format for agent work?
Match the format to the lifetime of the artifact. Ephemeral, human-facing, read-once-or-explored output should be HTML: a plan review, a data cut, a status page, a mockup. Durable knowledge that other agents and future sessions will read should be markdown: specs, decisions, runbooks, meeting notes, memory. And never invent a custom DSL for either job when a native format will do.
Further reading
- AI Engineer — HTML Is All Agents Need, James Russo, HeyGen
- Lenny's Newsletter — HTML is the new Markdown: how Anthropic engineers are building with Claude Code, Thariq Shihipar
- GitHub — Hyperframes, the Apache-2.0 HTML-to-video framework
- MDflow — Model-Agnostic AI Architecture · Context Engineering for AI Agents · Folder Descriptions as Agent Context · Markdown for AI · MCP documentation · API documentation