Markdown vs Markup
Six months ago, I wrote a post praising Markdown. About a month after that post, an Anthropic engineer, Thariq Shihipar, wrote a viral piece Using Claude Code: The unreasonable effectiveness of HTML, explaining why he switched Claude’s outputs from Markdown to markup (HTML). If you can’t stand to read it, here’s an interview summing up his position.
In the piece, Thariq points out a core problem that really resonated with me:
I also am increasingly not editing these [Markdown] files myself, but using them as specs and reference files. When I do make edits, I’m usually prompting Claude to edit them, which removes one of Markdown’s largest benefits.
I’m having this problem as well. Claude Code is great at creating long Markdown reports and design specs. When Claude was a little less competent, I felt the need to carefully review these (and I’d read and edit them in Obsidian before proceeding). But as Claude has gotten more competent, I’ve found myself just asking Claude to summarize these reports, and skipping reading them myself. It’s not just about trusting Claude more. Although Claude has improved a lot technically, it still can’t write anything that humans want to read, so it’s pretty tempting to skip reading these long Markdown reports.
Another argument goes: when context windows were small, the efficiency of Markdown was critical, but now that Claude’s models have a 1M token context window, you can “upgrade” to HTML. Simon Willison says that he defaulted to Markdown when the context windows were only 8K tokens, and it’s time to rethink that. It’s true that the bigger context window gives you a lot more flexibility, but context rot is still a thing, and it’s hard enough to stay within the token budget allocated by my Claude Max plan, so I’m not looking to burn tokens just because I can.
As Thariq points out, it’s getting harder and harder to stay in the loop, so if HTML does it for him, that’s a win. Obviously HTML is better for design mockups and visualizations, but most of the design specs and references don’t need major diagrams, so I’m mostly sticking with Markdown for these specs and references. But I’m still trying hard to figure out ways to stay in the loop.
As one final follow-up to my original post, back in April, I discussed llms.txt. In June, the SEO company Ahrefs studied the adoption of llms.txt. Among their customers, they found that more than a quarter of their sites have llms.txt files, but 97% of those llms.txt files were not fetched at all during the month they checked. I still have instructions in my CLAUDE.md to generate llms.txt, but it seems like this may not be doing much good. On the flip side, their analysis found that Claude Code was the second-largest fetcher of llms.txt (after GPTBot), so maybe llms.txt is helping Claude Code users.