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
Criteria for Choosing HTML or Markdown
An AI agent—AI that follows instructions to carry out research or other work—can produce deliverables in different formats. The choice depends on what the recipient needs to do. HTML is a candidate for comparing a long research report on screen and making a decision. Markdown is convenient for editing text directly and keeping a record of changes.
HTML describes the structure of a Web page, using tags such as <h1>Heading</h1> to identify elements such as headings and tables. Markdown organizes text with simple symbols: # at the start of a line marks a heading, and - marks a list item.
Claude Code is Anthropic’s AI tool for reading and writing files and carrying out development and other work. Its team’s use of HTML provides a starting point for comparing review, sharing, and editing needs. Separating the format used to give information to AI from the format used by people to read its output helps you choose for your own work.
How the Claude Code Team Uses HTML for Human Review
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 post proposes producing Claude Code’s plans, specs, analyses, and review materials in HTML so that people can read, share, and interact with them more easily. That is a separate claim from saying that HTML input improves AI comprehension or answer accuracy compared with Markdown.
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 for Plans, Research Reports, and Comparison Screens
An HTML deliverable can combine prose, tables, diagrams, code annotations, and controls such as buttons and input fields in one file. Even a long plan can show its overall structure and details on the same screen.
The Claude blog lists the amount of information a screen can show, visual clarity, ease of sharing, and the reader’s ability to interact with the content as benefits of HTML. It also describes how Claude Code can use the code and related materials it reads when creating a deliverable.[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 options side by side, including their conditions, benefits, and the limitations those benefits entail |
| Temporary editing screen | Group tasks, adjust instructions to AI, and export data in a fixed format |
“Information density” here does not mean fewer tokens (the units of text an AI system processes). It means showing more relationships that a human can understand on one screen.
Conditions for Using HTML as AI Input
Output that people can read easily and input that AI can process effectively are separate concerns. HTML is not always the best input format for AI. However, RAG—retrieving information relevant to a question and having AI use it to answer—can benefit from preserving Web-page headings and table structure.
The HtmlRAG paper focuses on information lost when retrieved Web pages are reduced to plain 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 AI needs structure such as:
- the hierarchy of main headings and subheadings
- row and column relationships in complex tables
- relationships between link destinations and anchor text (the visible text of a link)
- distinctions among code, quotes, and page navigation menus
- 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 information that is unnecessary for an answer: CSS (instructions for appearance, such as text styling and layout), JavaScript (programs that run interactions and other processes), and code comments. Those parts need to be removed while preserving headings, tables, and other structures relevant to the question.[2]
Input Format Performance Varies by AI System and Type of Work
The way instructions and information are presented to AI can affect performance. The same content has a different structure when presented as plain text, Markdown headings and lists, or pairs of field names and values. However, no single best format has been confirmed across all AI systems and types of work.
A Microsoft and MIT paper evaluated the same content represented as plain text (text without formatting), Markdown, JSON, and YAML across several GPT-family models (AI systems in the GPT series). JSON and YAML are data formats that represent information as pairs of field names and values. The results showed that performance changed by format, but no one format was always best across AI systems and types of work.[3]
Anthropic’s prompting guide for Claude describes XML tags as a way to organize complex instructions. XML tags mark the start and end of a section, as in <instructions> and </instructions>. Wrapping instructions, background information, input, and examples in separate tags clarifies what AI is being asked to do and what it should use as reference material. This serves a different purpose from displaying a deliverable in HTML.[4]
It is more practical to choose HTML, Markdown, XML, or JSON according to its purpose.
Markdown for Document Editing and Change History
Markdown uses simple symbols to write tables and code as well as headings and lists. It suits short technical documents and specs managed in Git, a tool that records changes to files and lets people compare versions.
Markdown works well for:
- READMEs (documents explaining a project’s purpose and how to use it) and short design notes
- specs whose changes people want to compare directly in Git
- documents people edit by hand frequently
- passing large amounts of text to AI while keeping input token counts and costs down
- static knowledge bases that store information as documents without interactive controls
- shared documents where JavaScript execution should be avoided
HTML supports varied ways of presenting information, but tags, CSS, and JavaScript tend to make files longer. When changes to appearance and behavior are mixed with text edits, it becomes harder to review the differences.
Publishing or sharing AI-generated HTML requires attention to external network calls, JavaScript whose behavior has not been checked, and XSS (an attack that runs unintended scripts (programs) on a Web page).
MDN describes CSP (Content Security Policy, a mechanism that limits which scripts, images, and other resources can load) and the sandbox attribute on iframe (an element that embeds another Web page within a page) as ways to restrict execution. The sandbox attribute limits the operations and permissions available to the embedded page.[5][6]
Formats for Review, Editing, and Data Exchange
In practical work, the choice depends on who will read the result, how it will be edited, and what needs to be verified. Even the same content may need different formats for a screen people review, instructions to AI, and data exchanged between services.
| 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 |
The uses compared above provide a basis for distinguishing a document whose text will be edited later and whose changes will be recorded in Git from a screen for comparing information and making a decision now. Markdown is a candidate for the former; HTML for the latter.
An Example Request for HTML 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 (reusable programs loaded separately) 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 interactive screen for review at the same time.
Summary: Match the Format to the Recipient’s Work and the Input’s Purpose
HTML is a candidate for reading and comparing deliverables on screen to make a decision; Markdown for editing text and keeping a record of changes. For AI input, the choice depends on its purpose: XML tags can separate complex instructions, while JSON can pass data with defined fields and formats.
Readability for people and improvements in AI answer accuracy are separate judgments. Using HTML as AI input still requires removing unnecessary parts while preserving the useful structure.
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.