Just the day before yesterday, Thariq from the Claude Code team wrote an article titled "Using Claude Code: The Unreasonable Effectiveness of HTML". Now, this article has exploded on X, viewed by 7.8 million people and bookmarked over 20,000 times!
There's a directly counter-intuitive reason for its explosive popularity:
Many people using AI will, by default, have it write in Markdown. For plans, Markdown; for summaries, Markdown; for PR explanations, still Markdown.
This is very reasonable. Markdown is simple, stable, easy to modify, and comfortable to keep in a code repository. For a long time, Markdown has almost been the most natural delivery format between AI and humans.
But Thariq says he now increasingly prefers having Claude Code output HTML, not Markdown.
Even more interesting is that he is also seeing more and more other people on the Claude Code team do the same.
This makes you curious:
Markdown is clearly simple, stable, and easy to edit, and it is practically the default format for AI-generated documentation. Why are the most cutting-edge members of the Claude Code team starting to switch to HTML?
Here is a summary of the core content from that article, well worth a read.
Claude Code Team Members Are Starting to Use Markdown Less
Markdown isn't broken. It's still simple, portable, easy to edit, and perfectly suitable for READMEs, documentation, code snippets, and lightweight logging.
Thariq also acknowledges that Markdown has become the mainstream format for agents and humans to communicate. Claude is even quite good at drawing ASCII art diagrams within Markdown.
But the use cases for Claude Code have changed.
Before, we had AI write Markdown because it was easy to modify. A person could open the file, manually adjust a few lines, change a title, or delete a section of text.
However, Thariq found that he now edits these files manually less and less often. Much of the Markdown isn't for manual editing but serves as specifications, reference materials, brainstorming results, or plans for the next steps.
And when he needs to make changes, he often doesn't open the file and edit it bit by bit himself. Instead, he continues telling Claude: change this here, rewrite that there.
This weakens one of Markdown's core advantages. The old question was: Is this format easy for humans to edit? The new question has become: Are humans still willing to read this format? Can they quickly understand it and continue making judgments based on it?
The Real Problem in the AI Era: AI Writes Too Much, and Humans Don't Want to Read It All
What this issue truly hits upon isn't a format debate over "HTML vs. Markdown," but a much broader problem: AI is now too good at writing.
We used to worry that AI couldn't write things down. Now, increasingly often, it really does write things, and does so very comprehensively.
An implementation plan can run hundreds of lines. A PR explanation can cover the background, changes, risks, and code snippets all in one go. A technical report can neatly organize the context, approach, data, and conclusions.
The question is, will people actually read it?
Many people using AI have likely had a similar experience: it generates a seemingly complete Markdown file. You open it, skim through, feel it's probably fine, and then just let it proceed.
Not because the content is necessarily bad, but because it's too long, too plain, and too much like a wall of text.
Markdown's mode of expression is linear. A heading, then a paragraph, then a list, then a code block. It's very clear when short, but as it gets longer, it really tests a person's patience.
So the core issue isn't whether AI can generate documentation. It's whether, after AI generates so much stuff, people are still willing to read it, whether they can understand it, and whether they will participate in the judgment process.
HTML is Different from Markdown; It Can Make AI Output Easier to Read
For many, the immediate first reaction to hearing "HTML" might be: Isn't that for web pages?
But the HTML Thariq is talking about isn't about writing websites, nor turning all documents into web pages. It's more about having Claude Code organize complex content into a page that is easier to digest.
Take the same implementation plan. If written in Markdown, it would most likely be a sequence of headings, lists, code blocks, and explanations. You'd have to read from top to bottom to slowly piece together the overall structure.
But if written in HTML, Claude can put different solutions into tabs, draw diagrams of key processes, place code snippets alongside, put conclusions up front, and collapse details out of sight.
In this scenario, you're not "finishing a document." You're browsing a well-organized workbench.
This is the core difference between HTML and Markdown: it doesn't just carry text; it can also carry layout, diagrams, interaction, and visual hierarchy.
Thariq mentioned that without HTML, Claude sometimes strains to "fake a visualization" in Markdown: drawing diagrams with ASCII characters, or even using Unicode characters to simulate colors.
This is interesting, but it also shows that Markdown itself isn't well-suited for complex visual expression. Rather than having Claude make do within Markdown, it's better to just let it draw things out using HTML.
HTML might not make the content any more correct, but it definitely makes the content easier for a person to see, understand, and review.
HTML Isn't Just for Viewing; It Can Also Be Used for Action
However, the most fascinating part of Thariq's article isn't just that HTML is easier to read.
What's truly eye-opening is that HTML can become a makeshift little tool.
That means Claude Code doesn't just generate a page for you to see. It can also generate an interface where you can operate, adjust, make selections, and then feed the results back to Claude Code.
For instance, say you need to re-prioritize 30 Linear tickets. Doing this just within a chat box would be very awkward. You'd have to say, one by one: put this one first, move that one back, let's skip these for now.
What's far more natural is letting Claude Code directly generate an HTML kanban board. The page has columns for Now, Next, Later, and Cut, with each ticket being a card you can drag and drop. Claude does an initial ranking, you then adjust it by dragging, and with a single click, you can export it as Markdown.
Another example is tuning a system prompt. Claude can generate an HTML page with an editable prompt on the left, sample inputs and a live preview on the right, and a token count and a copy button at the bottom.
This change is significant. HTML transforms Claude's output from "a document waiting for you to read" into "an interface you can operate."
When humans make judgments, the process is often not linear reading but involves comparing, moving, filtering, adjusting, and repeatedly checking effects. HTML accommodates these kinds of actions.
Final Thoughts: Markdown Suits Lightweight Text, HTML Suits Complex Plans
Of course, Thariq did not present HTML as a perfect solution.
HTML is usually more token-intensive and slower than Markdown. He noted that generating HTML can be 2 to 4 times slower. Version control is another issue: a Markdown diff is very clear, while an HTML diff is often much noisier.
So the article isn't arguing that Markdown is obsolete or that all AI output should become HTML.
More accurately, Markdown is well-suited for lightweight text, READMEs, simple explanations, and documents meant for long-term maintenance. HTML is better for complex plans, code explanations, visual reports, solution comparisons, interactive debugging, and one-off decision-making interfaces.
This isn't a battle of formats, but a matter of choosing the right tool for the right scenario.
And at the very end of his article, Thariq shared a crucial sentiment: he likes using HTML not just because it's more expressive, but because it allows him to stay in the loop.
To put it into even plainer terms: the human is not shut out of the AI's work process.
Claude Code generates a Markdown plan hundreds of lines long. You skim it, feel it's about right, and let it continue. On the surface, the AI is more automated; actually, the human is at greater risk of losing their sense of judgment.
The change that HTML brings is pulling the human back in. It makes plans easier to read, solutions easier to compare, code changes easier to review, parameters easier to adjust, and results easier to feed back to Claude.
So the value of HTML is not making Claude more independent, but making it easier for humans to intervene.
This is perhaps what Thariq means by HTML being "unreasonably effective": it seems like just a format change, but what it truly changes is the feeling of collaboration between humans and Claude Code.
Original Post Address: https://x.com/trq212/status/2052809885763747935