Will HTML replace Markdown when working with AI?
Quick Summary
Markdown was once the default choice when working with AI due to its lightweight nature and resource-saving capabilities—but that was a habit from the era of models with limited memory. With modern AI now handling context windows of up to millions of tokens, engineer Thariq Shihipar from the Claude Code team argues that HTML is a more suitable format for outputs requiring layout, color, and interactivity. His article analyzes 9 specific categories of scenarios—from code reviews and report generation to UI prototyping—where HTML performs significantly better than linear text. Additionally, JSON has its own role when the output needs to be machine-readable for further processing, rather than for direct human consumption. These three formats serve three different purposes, and explicitly specifying them in your prompts is a small change that makes a big difference in the quality of the results.
Markdown has been the default standard when working with AI for years, but an engineer from Anthropic's Claude Code team just raised a thought-provoking question: is that habit really the best choice? Thariq Shihipar's short post gathered over 15,000 likes on X in just a few days, and the reason is more convincing than you might think.
Markdown was born in the era of token-poor AI
Looking back at the days of GPT-4 with a context window of only 8,192 tokens, Markdown was an entirely reasonable choice. HTML was bulkier, consumed more resources, and in that constrained context, Markdown's simplicity was a real advantage for saving tokens. Thus, Markdown became the implicit standard, and that habit has stayed with us ever since. Even when Anthropic created the concept of Skills on Claude, they also set Markdown as the standard with the SKILL.md file—anyone who works with skills is surely familiar with this default.
However, current AI models operate on a completely different scale. Many models now support context windows from 200,000 to 1 million tokens, and the cost of processing is no longer a major barrier (as Thariq Shihipar points out). He argues that this is the perfect time to reconsider that default.
What can HTML do that Markdown cannot?
The core reason Thariq presents is simple: some types of information are inherently spatial, but Markdown forces them to be linear text. When you compare three technical approaches, you need to see them side-by-side, not read them one after another and try to keep them in your head. When you review a code diff, you need to see the structure of the changes, not just a wall of text.
HTML solves exactly that problem, which is why Thariq listed 9 specific groups of scenarios where HTML outclasses Markdown:
- Discovery and Planning: Comparing multiple approaches side-by-side instead of sequentially, and then transforming them into an implementation plan complete with flowcharts and timelines.
- Code Review and Understanding Project Structure: Highlighting changes directly with colors based on severity, and showing module diagrams as boxes and arrows—rather than plain text.
- UI Design: Displaying actual color palettes that can be copied instantly, and rendering UI component variants directly instead of describing them in words.
- Rapid Prototyping: Creating interactive animation adjustment panels with slider controls, and screens that can actually be clicked—something Markdown cannot express.
- Diagrams and Illustrations: Utilizing inline vector graphics to draw actual flowcharts, rather than stitching together ASCII characters.
- Slide Decks: A few
<section>tags and 20 lines of JavaScript can form a slide deck navigatable with arrow keys, without needing specialized software or export steps. - Research and Learning: Structuring documents with collapsible sections, code tabs, and glossaries—rather than dumping the entire content in a single vertical stream.
- Periodic Reports: Weekly status summaries with sparklines and color-coded progress indicators that actually encourage people to read, rather than just skim.
- Custom Editing Interfaces: Building drag-and-drop task boards or feature flag dashboards with dependency alerts—making it a functional tool rather than just text to read and forget.
Thariq has assembled 20 files illustrating all of these categories at thariqs.github.io/html-effectiveness, each of which opens directly in your browser without requiring any installation.
How to use HTML with AI in practice?
Applying this is not complicated; it just requires a shift in how you write prompts. Instead of letting the model choose the output format, explicitly specify HTML when the content is meant to be reviewed, interacted with, or shared with others.
For example, here is a prompt Thariq suggests for reviewing code:
Similarly, you can ask the AI to generate an implementation plan as HTML with a timeline and data flow diagram, or a weekly status report with small charts and progress-colored indicators.
Simon Willison, author of the famous tech blog, also admitted that this article made him reconsider his habit of using Markdown from the GPT-4 era until now. When modern AI models can embed vector graphics, interactive widgets, and in-page navigation, Markdown is no longer the obvious default choice.
Markdown still has its place, but not everywhere
Thariq is not saying we should always use HTML; rather, he makes a clear distinction: Markdown is suitable for casual chats, short code snippets, brief answers, and anything that is pure text. Meanwhile, HTML shines when the output requires spatial layouts, colors, interactivity, or complex structures—where the content is multi-dimensional enough that Markdown would start flattening the information rather than conveying it effectively.
Thariq doesn't mention JSON in his article, but it is also a very popular format when working with AI, especially for those who frequently use n8n, Make, or Zapier. Nevertheless, each format brings its own flavor to specific situations.
How Markdown, HTML, and JSON divide their usage
The debate is actually not just about Markdown or HTML. JSON is also a very popular format when working with AI, especially in data processing workflows and system integrations. These three formats serve three different purposes, and understanding those boundaries helps you choose the right tool for each situation.
- Markdown is best for text read directly in chat: notes, short explanations, code snippets, simple documents. Fast, lightweight, no need to open anything else.
- HTML is best when the output needs to be visualized, interacted with, or shared: reports with layouts, diagrams, comparison tables, slide decks, custom interfaces. Open with a browser and you are good to go.
- JSON is best when the output needs to be processed by a machine: storing structured data, transferring between systems, or feeding into the next step of a workflow. Humans can read it, but it is not meant for reading.
In other words, JSON does not compete with HTML or Markdown in terms of presentation; it serves an entirely different purpose. The real issue is that many AI users default to receiving output in Markdown even when they need HTML to view it or JSON to process it. By simply specifying your preference in the prompt, the AI will adapt.
What does this change for the average AI user?
If you use AI primarily for Q&A or writing, this change has less impact. But if you are using AI for more complex tasks like data analysis, project planning, document reviews, research synthesis, or creating reports for colleagues, this is a small prompt adjustment that creates a clear gap in output quality, regardless of which AI tool you are using.
You should try it once: next time you need the AI to compare options or summarize a complex document, add "generate as an HTML file" to the end of your prompt. Open that file in your browser and compare it to how you usually do it with Markdown or JSON—the results will speak for themselves.
