MD vs HTML: The 3-Question Framework
Stop picking sides. Let the document tell you what it wants to be.
Both camps are wrong. MD fundamentalists and HTML converts are both costing themselves tokens, edit cycles, and search relevance. The question isn't MD vs HTML — it's: for this specific document, who reads it, who edits it, and how long does it live? Answer those 3 and the format picks itself.
The 3 Questions
Every doc you produce with Claude has three properties. Each one votes for MD or HTML. When the 3 votes line up, you have your answer. When they split, use the hybrid pattern.
Q1: Who actually reads this?
Claude reads its own output back — constantly. If a doc gets re-ingested in a future session, codebase indexing, RAG over your notes, or an agent reading a spec before writing code, HTML eats your context window alive.
That's 3×. Multiply by 30 reference files in your project: 60k tokens burned. Retrieval pipelines also chunk HTML worse — expect 15–25% degradation in relevance because markup dilutes the semantic signal.
Q2: How many times will this get edited?
Claude does not edit HTML the way it edits MD. Modify a sentence in Markdown: ~5 lines of diff. Modify the same sentence in a styled HTML file: 40–100 lines of diff. Claude rewrites surrounding markup "to clean it up." Class names shift. Spacing tokens change. SVGs get re-emitted with slightly different coordinates. Nothing visibly broke. Everything is shifting underneath.
Over 5–10 iterations, your HTML document drifts. You end up with 3 different spacing systems and 4 color schemes in the same file. Call this markup drift — invisible until you diff version 1 against version 8.
Q3: How long does this thing live?
The grep test: in 6 months, can you grep -r "pricing" across your project and find this doc? In MD, yes. In HTML, you're searching for <h2>pricing</h2> and missing <h2 class="section-title" data-anchor="pricing">pricing</h2>.
The survivability test: open the HTML file in 3 years. Does the CDN link to Tailwind still work? Did Lucide change its API? A Markdown file from 2015 still opens cleanly.
Examples
| Document | Audience | Lifecycle | Horizon | Verdict |
|---|---|---|---|---|
| Product spec | Humans + Claude | Edited weekly | Months | MD |
| Weekly Slack update | Humans, once | Write once | A week | HTML if visual hierarchy adds info |
| Pull request description | Humans + GitHub + Claude | Write once | Indexed forever | MD |
| Animation prototype | Humans, in a meeting | Thrown away | One hour | HTML |
| System architecture doc | Everyone incl. future Claude | Evolves with system | Years | Hybrid |
One MD Source, Many HTML Renders
Write the canonical document in Markdown. Generate HTML views on demand for specific audiences. One architecture.md becomes:
- Exec view — one page, top-level, no jargon
- Engineering view — full doc with interactive SVG diagrams
- Onboarding view — same content plus inline quizzes and a progress tracker
Each HTML is a derived artifact. Regenerate it whenever the source changes. The MD stays reviewable, indexable, greppable. The HTML does the heavy presentation lift. Setup: a 10-line script that pipes your MD into Claude with three different system prompts. No infrastructure. No lock-in.
The Reversibility Test (30 seconds)
Before committing to HTML, ask: if I had to convert this back to clean Markdown right now, could I do it in one prompt?
If the answer is no, you've put content inside the markup. Content should always be cleanly extractable from the format. The day you can't separate them is the day the document becomes unmaintainable. This catches 90% of bad format choices in 30 seconds.
Legitimate Exceptions for HTML
- A sales demo or external one-pager where the aesthetic is the content
- A true one-shot you will literally never touch again
- An interactive prototype where the interaction is the deliverable
Takeaway
Stop having format opinions. Start asking 3 questions. Let the doc tell you what it wants to be. Most documents want to be Markdown. A few want to be HTML. One canonical source can produce both, on demand.
Format is a tool. It should be invisible. When you're arguing about it, you're losing.