Choosing AI Agent Output: HTML or Markdown
What you’ll learn
- Why the Claude Code team uses HTML and how that differs from claims about AI input accuracy
- When HTML or Markdown better supports review, sharing, and editing
- How to choose among HTML, Markdown, XML, and JSON for an AI agent deliverable
Choose AI Agent Output Formats by Review Purpose
After AI produces a long research result, HTML is useful when a reader wants to compare it on a web-page-like screen and make a decision. Markdown, a text format that uses simple symbols for headings and lists, is convenient when a reader wants to edit the prose and track what changed. Neither is always better; the right format depends on how a person will review the output and what they need to do with it next.
By the end of this article, you will have practical criteria for answering “How should HTML and Markdown be chosen from the reader’s next action?” in your own context.
The Original Claim Comes From Claude Code Team Practice
The primary source for this discussion is an Anthropic Claude blog post by Thariq Shihipar. The post was published on May 20, 2026, and Shihipar is introduced as a member of technical staff on the Claude Code team.[1]
The official blog post is not simply saying that HTML is easier for AI to understand than Markdown. More precisely, it proposes using HTML as a practical way to make plans, specs, analyses, and review outputs from Claude Code easier for humans to read, share, and operate.
Shihipar explains that he tended not to read Markdown files longer than 100 lines and that it was difficult to get others in his organization to read them. He then argues that HTML can use visual structure, diagrams, links, tabs, and interactions, making it easier for humans to stay involved in AI decisions.[1]
HTML Fits Complex Deliverables That Need Review
HTML is the format used to describe the structure of Web pages. As an AI agent output format, it can combine prose, tables, diagrams, code annotations, and interactive UI in one file.
The Claude blog lists information density, visual clarity, ease of sharing, two-way interactions, and Claude Code’s ability to ingest context as reasons HTML can be useful.[1]
In practical work, HTML is especially useful for deliverables like these.
| Deliverable | Benefit of HTML |
|---|---|
| Implementation plan | Show the big picture, data flow, risks, and code examples on the same screen |
| Change-proposal explanation | Lay out before-and-after changes, annotations, importance, and relationships with other features visually |
| Research report | Let readers move from summary to details, sources, and comparison tables |
| Design comparison | Compare several options side by side with conditions and tradeoffs |
| Temporary editing screen | Operate work grouping, AI-instruction adjustment, structured-data export, and similar workflows |
“Information density” here does not mean fewer tokens (the units of text an AI system processes). It means increasing the relationships a human can understand from one screen.
HTML as AI Input Is Useful Under Specific Conditions
HTML is not always the best input format for AI. However, when RAG finds information related to a question and gives it to AI, preserving Web-page headings and table structure can be useful.
The HtmlRAG paper focuses on information lost when retrieved Web pages are reduced to undecorated text, such as headings, tables, and links. It removes unnecessary parts, shortens the remaining content, and drops less relevant parts, then evaluates results on six sets of question-and-answer data.[2]
HTML can become useful as an input format when the model needs structure such as:
- heading hierarchy
- complex tables
- relationships between links and anchor text
- distinctions among code, quotes, and navigation
- the parent-child structure of headings and items across a page
At the same time, the paper is not recommending that raw HTML be passed through unchanged. Original HTML can be long and include unnecessary CSS, JavaScript, comments, and other noise, so irrelevant parts need to be removed while the useful structure remains.[2]
Format Matters, But No Universal Best Format Is Confirmed
Prompt format means how the same content is structured for AI, such as undecorated text, Markdown, or a data format that pairs field names with values. Research shows that format can affect performance, but no single best format has been confirmed across all AI models and jobs.
A Microsoft and MIT paper evaluated the same content represented as plain text, Markdown, JSON, and YAML across several GPT-family models. The results showed that performance changed by format, but no one format was always best across models and tasks.[3]
Anthropic’s prompting best practices for Claude also describe XML tags, not HTML, as a way to structure complex prompts. For example, tags such as <instructions> and <context> can separate instructions, context, input, and examples.[4]
So it is more practical to choose HTML, Markdown, XML, or JSON by use case than to treat them as a single ranking.
Markdown Still Fits Many Situations
Markdown is a lightweight document format for headings, lists, tables, and code blocks. It is still a good fit for short technical documents and specs managed in Git.
Markdown works well for:
- READMEs and short design notes
- specifications reviewed directly by comparing before-and-after changes in a history-management screen
- documents people edit by hand frequently
- passing large amounts of text to AI at lower cost
- static knowledge bases
- shared documents where JavaScript execution should be avoided
HTML is more expressive, but tags, CSS, and JavaScript can make files longer and diffs harder to review. When AI-generated HTML is published or shared, external network calls, unverified JavaScript, and XSS (unexpected script execution) need attention. MDN describes CSP (Content Security Policy, a mechanism for limiting which scripts, images, and other resources can load) and the sandbox (a restricted permission mode for embedded content) attribute on iframe as ways to control the execution scope of Web content.[5][6]
Choose HTML or Markdown by the Next Review, Editing, or Reuse Task
In practical work, the point is not to replace Markdown with HTML. The better approach is to choose the format based on the reader, editing method, and verification method.
| Purpose | Suitable format |
|---|---|
| Short instructions, guidance documents, and notes with change history | Markdown |
| Separating parts of complex AI instructions | XML, whose tags mark the start and end of each part |
| Supplying AI with information retrieved from Web pages | HTML with unnecessary parts removed |
| Long plans, research reports, and change-proposal explanations | HTML |
| Work requiring comparison, adjustment, or approval | Interactive HTML |
| Exchanging required fields accurately between services | JSON or another format with rules for fields and value types |
When reviewing AI agent outputs, I find it useful to first ask whether the output is a document to read later in Git or a screen for making a decision now. Markdown is a candidate for the former. HTML is a candidate for the latter.
A Prompt to Try in Claude Code
When using HTML, specify not only the output format but also the review and editing operations the human needs. Avoiding external libraries and external network calls also reduces sharing risk.
Create this project's implementation plan as a single HTML file.
Include the following elements.
- A diagram that explains the big picture
- The main data flow
- Important code examples
- Risks and unresolved questions
- Implementation steps
- Collapsible details
Do not just arrange long prose.
Design it as an interface that helps a human review,
judge, and correct the plan.
Do not use external libraries or external network calls.The important point in this prompt is that it specifies not only the output format, but also what the human needs to decide with the screen. HTML can be a document format and a temporary review UI at the same time.
Summary: Choose HTML or Markdown from the Next Task
The Claude Code team’s HTML workflow is not a complete replacement for Markdown. It is a proposal for helping humans understand, verify, and correct complex AI agent outputs.
- HTML is useful for long plans and research reports that humans need to read.
- HTML as AI input is conditionally useful in RAG when structure needs to be preserved.
- Cleaned HTML matters more than passing raw HTML unchanged.
- Markdown is still suitable for short documents, Git diffs, and frequent manual edits.
- XML tags fit complex prompt boundaries, and JSON fits strict data exchange.
HTML is getting attention not because AI cannot understand Markdown. It is getting attention because as AI deliverables become larger, humans need a format that keeps them in the review loop.
The first action is to decide whether the recipient will read, compare, edit, or preserve a diff after receiving the output. If strict data exchange or complex prompt boundaries are the main requirement, do not force the choice between HTML and Markdown; consider JSON or XML tags instead.
This article is a general information summary and is not legal advice. Confirm practical decisions with a qualified specialist.
References
- Anthropic, Using Claude Code: The unreasonable effectiveness of HTML, May 20, 2026
- Jiejun Tan, Zhicheng Dou, Wen Wang, Mang Wang, Weipeng Chen, Ji-Rong Wen, HtmlRAG: HTML is Better Than Plain Text for Modeling Retrieved Knowledge in RAG Systems, November 2024
- Jia He, Mukund Rungta, David Koleczek, Arshdeep Sekhon, Franklin X Wang, Sadid Hasan, Does Prompt Formatting Have Any Impact on LLM Performance?, November 2024
- Anthropic, Prompting best practices, Claude Platform Docs
- MDN Web Docs, Content Security Policy (CSP), MDN Web Docs
- MDN Web Docs,
<iframe>: The Inline Frame element, MDN Web Docs
For the latest releases and updates, check the official website and official documentation.