Using HTML Instead of Markdown: An Overlooked AI Output Format Optimization Technique in Prompt Engineering

From Markdown to HTML: An Overlooked Prompt Engineering Technique

For a long time, Markdown has been the de facto default output format when interacting with large language models. This habit dates back to the GPT-4 era—when the 8192-token context limit made Markdown's token efficiency advantage over HTML seem critically important. However, a recent article by Thariq Shihipar, a member of the Anthropic Claude Code team, is shaking this deeply entrenched default.

Prominent developer Simon Willison admitted after reading the article that it made him reconsider his long-standing habits. The core insight is simple yet highly illuminating: When you ask AI to output in HTML format, it can do far more than what Markdown allows.

Markdown vs. HTML: Understanding the Technical Essence of Both Formats

Before diving deeper, it's worth understanding the fundamental difference between these two formats. Markdown was created by John Gruber in 2004, with the design philosophy of making plain text readable while being convertible to HTML. It is essentially an extremely simplified subset of HTML—Markdown must ultimately be parsed into HTML to render in a browser. This means Markdown has been a "lossy compression" of HTML since its inception, sacrificing the vast majority of HTML's capabilities (CSS styling, JavaScript interactivity, SVG vector graphics) in exchange for writing simplicity. When an AI model outputs HTML directly, it's essentially skipping this "lossy compression" step and using the web's native expression language directly.

Understanding this, we can see more clearly: asking AI to output Markdown is essentially asking it to express itself in a constrained language.

Where HTML Output Surpasses Markdown

Expressive Power Beyond Plain Text

Markdown is fundamentally a simplified text markup language, excelling at structured text—headings, lists, code blocks, links. But when we need AI to explain complex concepts, plain text's expressiveness often falls short.

HTML opens up an entirely new dimension. When you ask Claude to output in HTML format in your prompt, it can:

Embed SVG diagrams: Draw flowcharts, architecture diagrams, and data visualizations directly in the output. SVG (Scalable Vector Graphics) is an XML-based vector graphics format that can be embedded directly in HTML documents without external files. Unlike bitmaps, SVG describes graphics using mathematical formulas, so it scales without loss. For AI models, generating SVG is essentially generating code that describes geometric shapes and text positions—a process highly consistent with generating natural language text. This enables LLMs to directly "draw" complex diagrams in HTML output without calling any external drawing tools or APIs.
Interactive components: Collapsible panels, tab switching, hover tooltips, and other interactive elements
In-page navigation: Automatically generate table of contents and anchor links for long documents
Color coding: Use colors to distinguish different levels of information, such as severity ratings in code reviews
Inline annotations: Add margin comments alongside code diffs

These capabilities are either completely impossible in Markdown or require extension syntax with questionable compatibility.

A Compelling Real-World Example

Thariq provides a highly persuasive prompt example in his article:

"Help me review this PR, create an HTML artifact to describe it. I'm not very familiar with streaming/backpressure logic, so please focus on that. Render the actual diff and add inline margin comments, color-code the findings by severity, and whatever else might be needed to convey the concept well."

The streaming/backpressure mentioned here are core concepts in distributed systems and asynchronous programming. When a data producer's speed exceeds the consumer's processing capacity, a backpressure mechanism allows the consumer to signal upstream to reduce the data sending rate, preventing memory overflow or system crashes. These concepts involve dynamic interactions between multiple components, which are often difficult to present intuitively in plain text—data flow direction, buffer states, and signal propagation processes. HTML paired with SVG animations or interactive diagrams can visualize these abstract concepts—which precisely illustrates why HTML output has irreplaceable advantages when explaining complex technical concepts.

Imagine the output from this prompt: a color-coded code review page with clear annotation bubbles beside key code lines, critical issues marked in red, suggestions in yellow, and informational notes in blue. The information density and readability of such output far exceeds what a block of Markdown text can achieve.

Notably, the "HTML artifact" mentioned here is closely related to the Artifacts feature Anthropic launched for Claude in 2024. Artifacts allow Claude to generate independent, previewable content blocks in a conversation sidebar, including HTML pages, SVG graphics, React components, and Mermaid diagrams. Users can view the rendered result directly in the browser rather than reading raw code. This feature provides a natural display environment for HTML output, enabling AI-generated rich media content to be presented instantly, significantly reducing the friction of manually saving and opening HTML code.

Thariq has also collected numerous similar examples at thariqs.github.io/html-effectiveness, showcasing the practical effects of HTML output in code review, concept explanation, data analysis, and other scenarios.

Why 2025 Is the Ideal Time for This Shift

Expanded Context Windows Eliminate Token Concerns

Back in early 2023, GPT-4's 8K token limit meant every token was precious. To understand the practical impact of this limitation, you need to understand the concept of tokens: tokens are the basic units by which large language models process text—typically one English word is split into 1-3 tokens, and each Chinese character is about 1.5-2 tokens. HTML tags like <div class="container"> consume significantly more tokens compared to Markdown's concise syntax. With an 8K token context window, input and output combined couldn't exceed approximately 6,000 English words, making the marginal cost of each token extremely high. The same content in HTML might consume 30-50% more tokens than Markdown due to tag overhead. In that era, choosing Markdown was a rational economic decision.

But today's situation is dramatically different. Claude's context window has expanded to 200K tokens, and GPT-4o has reached 128K. Mainstream models' context windows have expanded 15-25x, and combined with continuously declining per-token costs due to market competition and technological advances, the extra tokens consumed by HTML have become negligible in both cost and capacity. When tokens are no longer a scarce resource, we should reconsider: Is trading extra tokens for richer expression worthwhile?

The answer is almost certainly yes.

A Mindset Leap from Tool Building to Knowledge Presentation

Simon Willison had already been exploring the combination of HTML and AI, but his focus was primarily on building interactive tools—such as the various utility tools he publishes at tools.simonwillison.net. Thariq's article inspired a new direction: HTML isn't just suitable for building tools—it's even better as a vehicle for knowledge explanation and information presentation.

This means that even for a casual, one-off Q&A, HTML output may be more valuable than Markdown.

Practical Guide: How to Improve AI Output Quality with HTML

Five Scenarios Particularly Suited for HTML Output

Not every scenario requires HTML output. Here are the cases where switching formats yields the greatest benefit:

Complex concept explanations: Content involving processes, architectures, and multi-layered relationships
Code review and analysis: Requiring annotations and markings alongside code
Data comparison and visualization: Side-by-side display of multi-dimensional information
Educational materials: Learning content that benefits from interactive exploration
Technical documentation: Long documents with navigation structures

Three Key Points for Writing Effective HTML Output Prompts

When requesting HTML output, don't just write "output in HTML format." A more effective approach is to describe the visual and interactive experience you expect:

Specify visual needs: Indicate whether you need diagrams, color coding, or interactive components
Explain information hierarchy: Tell the model the priority and organization of information
Leave room for creativity: Add open-ended instructions like "whatever else might be needed to convey the concept well" to let the model exercise its own judgment

Scenarios Where Markdown Is Still the Better Choice

Of course, Markdown hasn't become obsolete. It remains the preferred choice in these scenarios:

Documents that need further editing and version control
Output embedded in Markdown ecosystems like GitHub or Notion
Simple text answers and lists
Scenarios requiring strict token consumption control

Reexamining Default Habits in AI Interaction

The real value of this topic lies not only in the specific advice to "use HTML instead of Markdown," but more importantly in the reminder: Many default practices in AI interaction may simply be stopgap measures from early technical limitations, rather than optimal solutions.

As model capabilities rapidly iterate, our usage patterns should upgrade in tandem. Shifting from token-conservation thinking to expression-richness thinking, from passively accepting default formats to actively choosing the best presentation method—this is perhaps one of the most noteworthy paradigm shifts in prompt engineering in 2025.

Key Takeaways

A member of the Anthropic Claude Code team proposes using HTML instead of Markdown as the AI output format, enabling SVG diagrams, interactive components, color coding, and other expressive capabilities far beyond plain text
The habit of using Markdown as the default output format originated from GPT-4 era token limitations, but in the age of 200K context windows, this constraint no longer holds
HTML output is particularly well-suited for complex concept explanations, code reviews, data visualization, and other scenarios requiring rich visual presentation
Effective HTML output prompts should describe the desired visual and interactive experience rather than simply requesting a format change
This shift reflects a paradigm evolution in AI interaction from token-conservation thinking to expression-richness thinking