Markdown vs HTML for AI-Readable Documentation
Heading
`) costs around five. A bold word in Markdown runs to roughly three tokens; `bold` runs to five. Cloudflare's own framing puts it plainly: a simple `## About Us` costs approximately three tokens in Markdown, while its HTML equivalent, once class attributes and wrapper elements are included, burns twelve to fifteen tokens before nav bars and script tags, none of which carry semantic value, are even counted. The compounding effect on real-world documentation pages is significant. Production HTML documentation typically includes navigation chrome, cookie banners, script tags, and deeply nested class attributes that exist entirely to serve browser rendering. An AI agent receives all of that. None of it informs the agent about the content. The practical implication is direct: lower token cost per page means an agent can reference more documentation within a single context window, covering longer articles, more sources, and broader subject matter in a single pass. Token efficiency is necessary but not sufficient, however. It says nothing about whether the model actually interprets the content correctly once it is inside the window. ## What benchmarks show about how accurately AI models parse each format The efficiency argument for Markdown is well-supported. The accuracy argument is more complicated. In GPT-based table extraction benchmarks, Markdown representations achieved 60.7% accuracy against 53.6% for HTML tables. RAG pipelines have shown accuracy improvements of up to 35% when ingesting Markdown over raw HTML. These are meaningful margins. The picture is not uniform, though: in controlled benchmarks where token budget is not the binding constraint, HTML can outperform Markdown on raw structural understanding of tables. The advantage of each format depends on what the model is being asked to do and what resources it has available to do it. He et al. (arXiv:2411.10541, 2024) produced a finding that deserves careful attention here. The same content, formatted as plain text, Markdown, JSON, and YAML respectively, produced meaningfully different results across reasoning, code generation, and translation tasks using GPT models. In one code translation task, GPT-3.5-turbo's performance varied by up to 40% depending solely on prompt template format. Larger models, including GPT-4, proved more robust to format variation; format sensitivity decreases with model scale, though it does not disappear entirely. The implication is that format choice matters most with smaller or older models and matters less, but still measurably, with frontier models. What this body of work leaves unresolved is the universal answer: no single format excels across all task types, and the right choice still depends on the specific task and model in question. ## Why Markdown is closer to how large language models were trained to think Training corpora for GPT, Claude, Gemini, and Llama all contain enormous volumes of Markdown: GitHub READMEs, Stack Overflow posts, Reddit comments, documentation sites, Jupyter notebooks. These models have encountered Markdown billions of times. They do not merely parse it; they produce it natively when asked to write structured content. HTML can represent identical content in dozens of structurally different ways. A heading can be an `
`, a `` with a class, a `` with a font-size rule, or a `` with a bold child. Markdown's constrained syntax gives the model far less surface area for misinterpretation. There is generally one way to write a second-level heading in Markdown.
A feedback loop follows from this alignment. AI reads Markdown most reliably, so AI produces Markdown natively. Teams feeding Markdown to AI get more coherent outputs. More Markdown is created, and more Markdown enters training data. This structural alignment is why Markdown's advantage holds even when HTML is technically capable of encoding the same information: capability and familiarity are different properties, and large language models are profoundly shaped by what they have seen.
If Markdown is structurally better for ingestion, the natural next question is whether it should be used everywhere. The answer depends on who is consuming the output, and that question surfaced a significant and instructive public debate.
## The case for HTML when the audience is human, not a model
In May 2026, Thariq Shihipar of Anthropic's Claude Code team published "Using Claude Code: The Unreasonable Effectiveness of HTML," which accumulated 4.4 million views within sixteen hours and is now cited alongside Anthropic's loops guide as core Claude Code workflow documentation. Shihipar's core observation: as agents produce longer, more complex outputs, Markdown becomes a reading bottleneck. A file exceeding a hundred lines is difficult for humans to navigate, and increasingly these files serve as specifications and reference documents rather than artifacts people edit line by line.
Andrej Karpathy offered a related recommendation around the same time: ask an LLM to structure its response as HTML, then view it in a browser. The recommendation is about the cognitive experience of the human reader, not the model's processing efficiency.
The neuroscience Shihipar invokes is worth sitting with. Roughly 30% of the human cerebral cortex is dedicated to visual processing; hearing claims about 3%, touch about 8%. Markdown barely activates the visual channel. It has no layout, no spatial hierarchy, no color, no interactive navigation. HTML offers all of those: collapsible sections, tabular layouts, styled comparisons, embedded diagrams, JavaScript-powered navigation, shareable anchor links, and pixel-level spatial relationships between elements. Markdown approximates some of these with ASCII art and Unicode, but the cognitive experience of reading a well-structured HTML document is substantively different from scrolling through a long flat Markdown file.
Simon Willison, creator of Datasette, noted that he had defaulted to Markdown since the GPT-4 era precisely because tight token limits made efficiency critical. Shihipar's piece caused him to reconsider, particularly for output. That reconsideration is itself instructive: the same person who chose Markdown for input was open to HTML for output because the constraints and consumers are different.
The Shihipar argument is not a rejection of Markdown for ingestion. It is a claim that Markdown is the wrong format when the artifact's primary consumer is a human reading AI-generated output, especially a long or structurally complex one.
## The security cost of rendering AI-generated HTML in live environments
The strongest objection to AI-generated HTML is not about tokens or readability. It is about what happens when HTML is rendered in a trusted browser context without sanitization.
When AI output includes HTML or JavaScript and is rendered immediately, it opens a direct path to cross-site scripting. A malicious script tag in AI-generated content executes on the user's machine if the browser trusts the source. The attack vectors specific to AI-generated HTML are worth naming: zero font-size or zero-opacity text, invisible to human code review but fully present in the DOM; hidden HTML sections that a human skimming source would miss; and JavaScript-embedded prompt injections that execute dynamically.
Real-world precedent exists. A vulnerability in the DeepSeek AI platform enabled a full account takeover by chaining a prompt injection with an XSS exploit. An attacker uploaded a malicious text file containing a base64-encoded JavaScript payload; when processed by a victim's account, the AI decoded and executed the script in the victim's browser, stealing the session token.
Markdown's structural constraint is, in this context, a security property. Without a rendering engine, there is no execution surface for injected scripts. A Markdown file has no DOM, no script context, nothing to execute. The practical implication for teams is that using HTML for AI output is reasonable in controlled, sandboxed environments; deploying it in live product contexts without strict sanitization introduces attack surface that Markdown avoids by design.
## How the ingestion and output stages of an AI pipeline call for different formats
The debate is usually framed as a binary, but the two camps are answering different questions. Shihipar and Karpathy are talking about AI output consumed by humans. The token-efficiency data and RAG benchmarks are talking about AI input, documentation fed into a model. Conflating those two questions produces the false choice.
For documentation that flows into an AI agent, Markdown is the rational default. Lower token cost means more content fits in context. Structural consistency means the model interprets hierarchy reliably. A diff-friendly plain-text source means documentation can be versioned and reviewed by humans without specialized tooling.
For AI-generated output consumed visually by humans, particularly long or structurally complex documents read once rather than iterated upon, HTML earns its token cost. Dense technical reports, long reference documents, and complex comparisons benefit from layout and navigation. The token overhead is a one-time rendering cost, not a recurring ingestion cost.
A useful decision rule emerges from this framing. If the primary consumer of the artifact is another model, Markdown. If the primary consumer is a human reading a long, visually complex document once, HTML, with sanitization. If the consumer is a human who will edit the artifact, version it, or pipe it through further model calls, Markdown. The synthesis is not that one format is superior; it is that treating format as a single decision for the entire pipeline produces the wrong answer at at least one stage.
## How RAG pipelines expose the consequences of ignoring Markdown's structural properties
Retrieval-augmented generation systems split documentation into chunks, index them, and retrieve relevant pieces when answering queries. The chunking strategy determines whether agents return complete, accurate information or fragmented, incoherent responses, and format directly shapes what chunking strategies are available.
Markdown's heading hierarchy provides natural chunk boundaries that align with how humans organized the content. H2 sections typically represent complete ideas and work well as standalone chunks. Related H3 subsections can be grouped when they fit within token limits. Code blocks should remain intact; splitting a function disrupts comprehension and often produces code the agent cannot execute correctly. For API documentation, each endpoint description should stay within a single chunk to preserve complete implementation details.
HTML creates compounding overhead in this pipeline. Navigation chrome, script tags, class attributes, and wrapper elements enter the chunk alongside the content, consuming tokens that could carry more documentation. Cloudflare's data suggests that converting documentation pages from HTML to Markdown reduces token consumption by over 90%, a reduction that directly expands how much documentation an agent can reference per query.
JavaScript-heavy documentation sites present a separate barrier: AI agents cannot execute client-side code or interact with JavaScript-based navigation. Content that exists only in the rendered DOM is invisible to the agent, regardless of how well the underlying HTML is structured.
Stale documentation carries different risk in a RAG context than it does for human readers. Humans apply skepticism when docs seem outdated; they notice that an API version number looks old or that a screenshot shows a deprecated UI. AI agents retrieve and treat documentation as current truth on every request, generating code against deprecated endpoints or removed parameters without flagging the inconsistency. The structural implication is that documentation written for RAG should use heading hierarchies as semantic boundaries, with each section containing a complete, self-sufficient thought that holds meaning when retrieved independently of its surrounding context.
## How infrastructure providers have operationalized Markdown delivery for AI systems
The web is built in HTML, and page weight has been increasing steadily. HTML-to-Markdown conversion has become a standard step in AI pipelines, but performing it at query time wastes computation and adds processing complexity at a point where latency matters.
Cloudflare responded with a "Markdown for Agents" feature. When an AI system requests a page from a Cloudflare-served site with the feature enabled, sending `Accept: text/markdown` causes Cloudflare's network to convert the HTML to Markdown on the fly before delivery. The conversion happens at the edge, before the content reaches the agent, removing the conversion step from the agent's processing budget entirely.
Read the Docs serves Markdown automatically to clients that request it via HTTP content negotiation, enabled by default across all Read the Docs-hosted documentation domains with no configuration required.
The mechanism underlying both approaches is content negotiation, a standard embedded in HTTP for nearly three decades. A browser sends `Accept: text/html` and receives a rendered page. An AI agent sends `Accept: text/markdown` and receives clean Markdown. The same content, negotiated into the appropriate format for the audience, without requiring two separate publishing workflows.
The fact that infrastructure providers are now operationalizing format negotiation at the network level is itself informative. It signals that the Markdown-for-ingestion pattern has moved from best practice to expected behavior, and that the tooling has matured to the point where format-aware delivery is a default, not an optimization. The interesting work is now in the decisions above the infrastructure: which documents need to be chunked how, which outputs warrant HTML, and who, in any given moment, is actually doing the reading.
` with a bold child. Markdown's constrained syntax gives the model far less surface area for misinterpretation. There is generally one way to write a second-level heading in Markdown. A feedback loop follows from this alignment. AI reads Markdown most reliably, so AI produces Markdown natively. Teams feeding Markdown to AI get more coherent outputs. More Markdown is created, and more Markdown enters training data. This structural alignment is why Markdown's advantage holds even when HTML is technically capable of encoding the same information: capability and familiarity are different properties, and large language models are profoundly shaped by what they have seen. If Markdown is structurally better for ingestion, the natural next question is whether it should be used everywhere. The answer depends on who is consuming the output, and that question surfaced a significant and instructive public debate. ## The case for HTML when the audience is human, not a model In May 2026, Thariq Shihipar of Anthropic's Claude Code team published "Using Claude Code: The Unreasonable Effectiveness of HTML," which accumulated 4.4 million views within sixteen hours and is now cited alongside Anthropic's loops guide as core Claude Code workflow documentation. Shihipar's core observation: as agents produce longer, more complex outputs, Markdown becomes a reading bottleneck. A file exceeding a hundred lines is difficult for humans to navigate, and increasingly these files serve as specifications and reference documents rather than artifacts people edit line by line. Andrej Karpathy offered a related recommendation around the same time: ask an LLM to structure its response as HTML, then view it in a browser. The recommendation is about the cognitive experience of the human reader, not the model's processing efficiency. The neuroscience Shihipar invokes is worth sitting with. Roughly 30% of the human cerebral cortex is dedicated to visual processing; hearing claims about 3%, touch about 8%. Markdown barely activates the visual channel. It has no layout, no spatial hierarchy, no color, no interactive navigation. HTML offers all of those: collapsible sections, tabular layouts, styled comparisons, embedded diagrams, JavaScript-powered navigation, shareable anchor links, and pixel-level spatial relationships between elements. Markdown approximates some of these with ASCII art and Unicode, but the cognitive experience of reading a well-structured HTML document is substantively different from scrolling through a long flat Markdown file. Simon Willison, creator of Datasette, noted that he had defaulted to Markdown since the GPT-4 era precisely because tight token limits made efficiency critical. Shihipar's piece caused him to reconsider, particularly for output. That reconsideration is itself instructive: the same person who chose Markdown for input was open to HTML for output because the constraints and consumers are different. The Shihipar argument is not a rejection of Markdown for ingestion. It is a claim that Markdown is the wrong format when the artifact's primary consumer is a human reading AI-generated output, especially a long or structurally complex one. ## The security cost of rendering AI-generated HTML in live environments The strongest objection to AI-generated HTML is not about tokens or readability. It is about what happens when HTML is rendered in a trusted browser context without sanitization. When AI output includes HTML or JavaScript and is rendered immediately, it opens a direct path to cross-site scripting. A malicious script tag in AI-generated content executes on the user's machine if the browser trusts the source. The attack vectors specific to AI-generated HTML are worth naming: zero font-size or zero-opacity text, invisible to human code review but fully present in the DOM; hidden HTML sections that a human skimming source would miss; and JavaScript-embedded prompt injections that execute dynamically. Real-world precedent exists. A vulnerability in the DeepSeek AI platform enabled a full account takeover by chaining a prompt injection with an XSS exploit. An attacker uploaded a malicious text file containing a base64-encoded JavaScript payload; when processed by a victim's account, the AI decoded and executed the script in the victim's browser, stealing the session token. Markdown's structural constraint is, in this context, a security property. Without a rendering engine, there is no execution surface for injected scripts. A Markdown file has no DOM, no script context, nothing to execute. The practical implication for teams is that using HTML for AI output is reasonable in controlled, sandboxed environments; deploying it in live product contexts without strict sanitization introduces attack surface that Markdown avoids by design. ## How the ingestion and output stages of an AI pipeline call for different formats The debate is usually framed as a binary, but the two camps are answering different questions. Shihipar and Karpathy are talking about AI output consumed by humans. The token-efficiency data and RAG benchmarks are talking about AI input, documentation fed into a model. Conflating those two questions produces the false choice. For documentation that flows into an AI agent, Markdown is the rational default. Lower token cost means more content fits in context. Structural consistency means the model interprets hierarchy reliably. A diff-friendly plain-text source means documentation can be versioned and reviewed by humans without specialized tooling. For AI-generated output consumed visually by humans, particularly long or structurally complex documents read once rather than iterated upon, HTML earns its token cost. Dense technical reports, long reference documents, and complex comparisons benefit from layout and navigation. The token overhead is a one-time rendering cost, not a recurring ingestion cost. A useful decision rule emerges from this framing. If the primary consumer of the artifact is another model, Markdown. If the primary consumer is a human reading a long, visually complex document once, HTML, with sanitization. If the consumer is a human who will edit the artifact, version it, or pipe it through further model calls, Markdown. The synthesis is not that one format is superior; it is that treating format as a single decision for the entire pipeline produces the wrong answer at at least one stage. ## How RAG pipelines expose the consequences of ignoring Markdown's structural properties Retrieval-augmented generation systems split documentation into chunks, index them, and retrieve relevant pieces when answering queries. The chunking strategy determines whether agents return complete, accurate information or fragmented, incoherent responses, and format directly shapes what chunking strategies are available. Markdown's heading hierarchy provides natural chunk boundaries that align with how humans organized the content. H2 sections typically represent complete ideas and work well as standalone chunks. Related H3 subsections can be grouped when they fit within token limits. Code blocks should remain intact; splitting a function disrupts comprehension and often produces code the agent cannot execute correctly. For API documentation, each endpoint description should stay within a single chunk to preserve complete implementation details. HTML creates compounding overhead in this pipeline. Navigation chrome, script tags, class attributes, and wrapper elements enter the chunk alongside the content, consuming tokens that could carry more documentation. Cloudflare's data suggests that converting documentation pages from HTML to Markdown reduces token consumption by over 90%, a reduction that directly expands how much documentation an agent can reference per query. JavaScript-heavy documentation sites present a separate barrier: AI agents cannot execute client-side code or interact with JavaScript-based navigation. Content that exists only in the rendered DOM is invisible to the agent, regardless of how well the underlying HTML is structured. Stale documentation carries different risk in a RAG context than it does for human readers. Humans apply skepticism when docs seem outdated; they notice that an API version number looks old or that a screenshot shows a deprecated UI. AI agents retrieve and treat documentation as current truth on every request, generating code against deprecated endpoints or removed parameters without flagging the inconsistency. The structural implication is that documentation written for RAG should use heading hierarchies as semantic boundaries, with each section containing a complete, self-sufficient thought that holds meaning when retrieved independently of its surrounding context. ## How infrastructure providers have operationalized Markdown delivery for AI systems The web is built in HTML, and page weight has been increasing steadily. HTML-to-Markdown conversion has become a standard step in AI pipelines, but performing it at query time wastes computation and adds processing complexity at a point where latency matters. Cloudflare responded with a "Markdown for Agents" feature. When an AI system requests a page from a Cloudflare-served site with the feature enabled, sending `Accept: text/markdown` causes Cloudflare's network to convert the HTML to Markdown on the fly before delivery. The conversion happens at the edge, before the content reaches the agent, removing the conversion step from the agent's processing budget entirely. Read the Docs serves Markdown automatically to clients that request it via HTTP content negotiation, enabled by default across all Read the Docs-hosted documentation domains with no configuration required. The mechanism underlying both approaches is content negotiation, a standard embedded in HTTP for nearly three decades. A browser sends `Accept: text/html` and receives a rendered page. An AI agent sends `Accept: text/markdown` and receives clean Markdown. The same content, negotiated into the appropriate format for the audience, without requiring two separate publishing workflows. The fact that infrastructure providers are now operationalizing format negotiation at the network level is itself informative. It signals that the Markdown-for-ingestion pattern has moved from best practice to expected behavior, and that the tooling has matured to the point where format-aware delivery is a default, not an optimization. The interesting work is now in the decisions above the infrastructure: which documents need to be chunked how, which outputs warrant HTML, and who, in any given moment, is actually doing the reading.
