HTML or Markdown? Before outputting in Claude Code format, take 30 seconds to think about these things

Claude Code engineers advocate replacing Markdown with HTML as the default format for AI outputs, sparking debates both for and against. Some columnists suggest users should spend 30 seconds evaluating these issues before requesting AI to generate formats.

Claude Code engineers advocate HTML replacing Markdown

As AI agents become increasingly popular, Markdown has become the default standard for communication between most AI systems and users.

However, recently, Claude Code engineer Thariq Shihipar posted that, with the significant improvement in AI agent capabilities, Markdown is gradually becoming a limitation. Files over 100 lines are hard to read, and sharing and visual presentation pose many inconveniences. Switching Claude Code’s output format to HTML could bring notable advantages.

He pointed out that HTML has extremely high information density, can present design data via CSS, draw illustrations with SVG, and even combine JavaScript to achieve two-way interactive functions.

These features make documents more visually organized and greatly increase team members’ willingness to read long technical specifications and reports. When sharing, HTML files can be uploaded to cloud storage and viewed easily via links, avoiding the lack of native support for Markdown in some browsers.

Image source: Thariq Shihipar　Claude Code engineers advocate HTML replacing Markdown

HTML or Markdown? Think about three questions before output

Shihipar’s idea of “HTML replacing Markdown” quickly sparked heated discussion and skepticism in the community. But the real focus should be: When should you use HTML, and when should you use Markdown?

Columnist The Smart Ape, who focuses on cryptocurrency and AI, believes that debating which format is better is pointless. The choice of format depends entirely on the audience, editing frequency, and lifecycle of the document. Choosing the wrong format can waste a lot of tokens and editing time, and even affect database search accuracy.

He recommends considering these three questions before asking Claude Code to generate a format.

⭐Who will read this document?

If this document needs to be re-read by Claude or other AI agents in the future—for example, as an index for a code repository or a technical specification—Markdown is definitely the best choice.

The Smart Ape points out that HTML contains a large amount of styles and tags, which can consume more than three times the number of tokens, and dilutes semantic signals, leading to a 15% to 25% decrease in AI relevance during subsequent retrievals. However, if the document is a one-time report for human reading, HTML can be considered.

⭐How many times will this document be edited?

When modifying Markdown files, AI usually only needs to replace a few lines of text. When editing styled HTML files, AI often rewrites surrounding markup language as well. After 5 to 10 edits, HTML files can suffer from severe “tag drift,” with mixed spacing systems and color configurations.

The Smart Ape believes that if a document requires frequent edits, using Markdown ensures content stability. HTML is only suitable for final publication formats.

⭐How long is the lifecycle of this document?

The longevity of a document is also a major consideration. After six months, developers can easily search for specific Markdown content within a project using keywords, but HTML may fail due to complex tag structures.

Additionally, a Markdown file from years ago can still be opened cleanly, whereas HTML files that rely on external resources may face style failures. Therefore, for core documents that need long-term preservation and retrieval, Markdown should be the baseline.

The Smart Ape believes the best approach is to treat Markdown as a single source of truth and dynamically generate HTML for different audiences as needed.

Image source: The Smart ApeHTML or Markdown? Think about three questions before output

⭐Spend 30 seconds first to perform a reversible test

The Smart Ape also shared a 30-second reversible test as a final quality check.

Before deciding to use HTML, ask yourself: Can this document be perfectly converted back into clean Markdown with a single prompt? If the answer is no, it indicates that the content is deeply tied to markup language, and maintaining this document in the future will be difficult.

Computer scientist: Looking forward to a major upgrade in AI interaction

Although the debate over HTML versus Markdown has sparked both support and opposition, OpenAI former computer scientist Andrej Karpathy remains optimistic.

He pointed out that, at the end of a prompt, requesting an LLM to output in HTML format and then opening the generated file in a browser is very effective at this stage. He has also successfully used AI to produce outputs in slideshow formats and more.

He believes humans are visual creatures, and as AI technology advances, output formats will undergo several stages of upgrade. He even predicts that this development will eventually lead to interactive videos or simulated environments generated directly by neural networks.

Further reading:
Claude Code leader: Coding has already been solved by AI! Why is “/loop” the future?

Claude Code + OnlyFans earns thousands of dollars a month? How credible is the AI startup article with 3.4T views?