Should AI Output Markdown or HTML? Two Dimensions to Help You Choose Quickly

A Discussion About AI Output Formats

Ask AI to explain the TCP three-way handshake, and the generated HTML file far surpasses Markdown plain text in visual quality. This simple comparison sparked a deep discussion about AI output format selection.

The TCP Three-Way Handshake is the core mechanism by which the Transmission Control Protocol establishes reliable connections: the client first sends a SYN packet, the server responds with SYN+ACK, and the client sends an ACK to complete the connection. This process involves network protocols, state machine transitions, sequence number mechanisms, and many other concepts. Pure text descriptions can easily lose readers in the details, while visual sequence diagrams and state flow charts dramatically improve comprehension—which is exactly why it was used to argue HTML's advantage.

Thoric from the Claude Code team recently published the article HTML is the New Markdown, stating he basically no longer writes Markdown files, instead using Claude Code to generate HTML. Well-known developer Capacity also responded that "having LLMs output HTML directly works extremely well."

So should we always deliberately ask AI to generate HTML from now on? The answer is: not necessarily. It all depends on the use case.

Markdown vs. HTML: Positioning Differences Determine Applicable Scenarios

To make the right AI output format choice, you first need to understand the essential differences between these two formats.

Markdown is the mainstream format for communication between AI Agents and users. Created by John Gruber in 2004, it was designed to let people write documents in an easy-to-read, easy-to-write plain text format that can optionally be converted into structured HTML. Its syntax was inspired by plain text email formatting conventions. Today it has become the default documentation format for mainstream platforms like GitHub, Notion, and Obsidian, and is the default output format for virtually all large language models. The syntax is simple, editing is convenient, and it can define headings, paragraphs, and basic rich text. For content that needs frequent modifications and long-term maintenance, Markdown's lightweight nature is an irreplaceable advantage.

HTML (HyperText Markup Language) is the core medium for interacting with browsers. Born in 1991 and invented by Tim Berners-Lee, it's one of the foundational technologies of the World Wide Web. HTML defines page structure through a tag system, pairs with CSS for styling and JavaScript for interactivity, forming the three core technologies of the modern Web stack. It supports rich colors, layouts, charts, and even animations, far exceeding plain text in visual presentation. When you need output that "looks professional," HTML is the better choice.

The essential difference between the two: Markdown is a lightweight markup language that pursues "writing experience"; HTML is a complete page description language that pursues "presentation capability."

Markdown's Limitations: Thoric's Core Arguments

Information Overload Is a Real Pain Point

Thoric raised a point that resonated widely: "I find it hard to read through Markdown files longer than a hundred lines anymore."

This truly strikes a chord with many people. When AI outputs large blocks of Markdown text, our first reaction is often not to read line by line, but to ask it to "condense it further." Plain text with excessive information density actually reduces information delivery efficiency.

It's worth noting that Thoric's perspective attracted widespread attention partly because of who he is. Claude Code is Anthropic's command-line AI programming assistant that allows developers to interact directly with Claude models in the terminal to perform code generation, debugging, refactoring, and other tasks. It forms part of the mainstream AI-assisted development tool ecosystem alongside Cursor, GitHub Copilot, Windsurf, and similar tools. When AI-generated content expands from code snippets to complete technical proposals and documentation, the choice of output format becomes a user experience issue that cannot be ignored.

Scenarios Where HTML Output Works Best

Thoric listed several typical scenarios where HTML is better suited than Markdown:

Scenario 1: Solution Exploration and Comparative Analysis. For example, implementing three debounce strategies in React and analyzing their pros and cons. Debounce is a classic performance optimization technique in frontend development, used to limit the actual execution count of high-frequency triggered events (such as user input, window resizing). In the React ecosystem, common implementation strategies include: the traditional approach using lodash.debounce with useCallback, the native Hook approach based on useEffect and setTimeout, and newer approaches leveraging React 18+ concurrent features like useDeferredValue. Each strategy has its own trade-offs in performance overhead, code complexity, and compatibility with the React lifecycle. HTML can use tables, color annotations, and card layouts to clearly present the advantages and disadvantages of each approach, with the recommended solution highlighted at the end. The same content displayed in Markdown would likely be a large block of text that's difficult to scan quickly.

Scenario 2: Design Direction Reviews. When designers have four visual directions (minimalist, illustration-based, playful, etc.) and can't decide, HTML format presentation is more conducive to review discussions than plain text.

Scenarios Where HTML Is Less Suitable

But some of Thoric's examples feel like a stretch. For instance, he showcased a complete development plan for "adding a comment feature to task cards," including timeline planning, milestones, data flow diagrams, and more.

The problem is: this type of plan changes frequently during development. The timeline might shift from two weeks to three, and the scope might expand or shrink. Using HTML to maintain a continuously changing design document carries extremely high maintenance costs. In this scenario, Markdown's editability advantage shines through.

This also involves an important engineering practice issue: the natural compatibility between Git version control and Markdown. Git is currently the most mainstream distributed version control system, and one of its core strengths is precise difference tracking (diff) for plain text files—it can show file modifications line by line. Markdown, as a plain text format, is perfectly compatible with Git's diff mechanism, and every text modification can be clearly marked and reviewed. HTML files, on the other hand, contain extensive tags and style code, so a simple content change might cause numerous irrelevant tag changes in the diff, making code review extremely difficult. This is why Markdown remains irreplaceable for project documentation scenarios requiring multi-person collaboration and version iteration.

A Scenario-Based Selection Framework: Two Dimensions for Choosing AI Output Format

When choosing between Markdown and HTML, you can use two core dimensions to make your decision:

Dimension 1: Does the Content Need Long-Term Maintenance?

If the content needs repeated modifications and version iterations, choose Markdown. It's lightweight, easy to edit, and naturally compatible with version control tools like Git. Project documentation, API references, and development plans all fall into this category.

Dimension 2: Do You Need Efficient Comprehension Right Now?

If you're learning systematic knowledge and don't want to face Markdown's "wall of text," have AI generate HTML. For scenarios like learning the TCP three-way handshake, understanding design patterns, or comparing technical solutions, HTML's visual presentation can significantly improve comprehension efficiency.

Of course, choosing HTML also comes with trade-offs to consider:

• Generation time is approximately 2-4x longer than Markdown
• Token consumption is significantly higher

Tokens are the basic unit of measurement for how large language models process text, roughly equivalent to one English word or 2-3 Chinese characters. Mainstream models (such as GPT-4o, Claude 3.5 Sonnet, etc.) charge based on the number of input and output tokens. HTML output consumes more tokens because HTML tags themselves take up significant characters—a simple bold text requires only **text** (6 extra characters) in Markdown, but needs <strong>text</strong> (17 extra characters) in HTML. Add CSS style definitions, layout structure code, and other elements, and token consumption can easily double or more. For personal learning scenarios, this cost difference is negligible; but for enterprise applications making millions of API calls daily, the cost difference from format choice becomes quite substantial.

However, for learning scenarios, this trade-off is entirely worthwhile. The improvement in comprehension efficiency is far more valuable than saving a few seconds of generation time.

The Future of AI Output: From Text to Visual Interaction

Capacity offers a more forward-looking perspective.

He pointed out an interesting asymmetry: AI input is moving toward voice (because the cost of expression is low, as with voice input products like Typeless), while AI output should move toward visualization. The reason is simple—one-third of the human brain's cortex is involved in visual processing, and we are inherently good at processing images, animations, videos, and other visual information.

This claim has solid neuroscience backing. Research shows that approximately 30% of neurons in the human cerebral cortex are dedicated to visual information processing, compared to only 8% for touch and 3% for hearing. MIT research also found that the human brain can process an image in just 13 milliseconds, far faster than the time needed to read an equivalent amount of text. From the perspective of Cognitive Load Theory, visual presentation effectively reduces working memory burden by encoding information as spatial relationships, color differences, and shape patterns, allowing the brain to devote more cognitive resources to understanding and analysis. This is the fundamental reason why data visualization and infographics are so effective in business and education.

From this perspective, AI generating HTML instead of Markdown is just an intermediate stage, not the endgame. The more likely future form is interactive video—users acquiring information by interacting with video. Currently popular Flipbook products are already exploring this direction. Flipbook is a recently emerging category of AI content products that transforms traditional text or document content into pageable, interactive visual presentations, similar to digitized flip books. More broadly, Interactive Video already has mature applications in the edtech field—platforms like H5P and Eko allow users to make choices, answer questions, or explore different branches during video playback. Combining this concept with AI generation capabilities means that future AI output may no longer be static text or pages, but dynamic media that adjusts content depth and presentation style in real-time based on user interest.

Summary: Choose AI Output Format Based on Your Scenario

Scenario	Recommended Format	Core Reason
Long-term maintained documentation	Markdown	Easy to edit, easy to version control
Solution comparison and decision-making	HTML	Visual presentation is more efficient
Systematic knowledge learning	HTML	Significantly improves comprehension
Code PR descriptions	HTML (marginally)	Better readability but high maintenance cost
Development plan design	Markdown	Content changes frequently, needs flexible editing

Don't blindly follow the claim that "HTML is the new Markdown," and don't stubbornly cling to Markdown either. Choosing format based on the content's lifecycle and reading context is the truly efficient approach.

In an era of rapidly iterating AI tools, maintaining dialectical thinking is more important than following any single "best practice."