If you're letting an AI agent maintain your docs, you're picking a format on its behalf, and Markdown is the wrong default.
I've spent the last several months using Claude Code, GitHub Copilot and OpenAI Codex to write and maintain documentation across a handful of repos. The same pattern keeps showing up: the models are noticeably better at editing HTML than Markdown, and the gap is widest on exactly the docs that matter, the long-lived ones that get edited constantly.
Markdown looks simple. That's the problem.
Markdown's appeal is that it's "just text". But the rules are surprisingly fiddly when an LLM is doing surgery on a 600-line file:
- Indentation inside a nested list item has to be exactly two or four spaces, and getting it wrong silently breaks rendering.
- A blank line in the wrong place collapses a list, or merges two paragraphs into one.
- Tables are positional. Miscount the pipes and the whole row shifts.
- Inline HTML, code fences, and Markdown syntax interact in ways that even experienced humans get wrong.
When a model makes a small edit to Markdown, the failure modes stay invisible until you render the page. The diff looks fine, the tests (if you have any) still pass, and the output is subtly broken.
HTML is verbose, and that's exactly why models do better with it
HTML's tags are explicit. Every container has an opening and closing marker, there's no whitespace-sensitive syntax, and there are no positional tokens. A model editing HTML has unambiguous structural anchors to work against:
<section id="install">
<h2>Installation</h2>
<ol>
<li>Clone the repo.</li>
<li>Run <code>bun install</code>.</li>
</ol>
</section>Ask Claude Code to "add a step about environment variables after the install step" and it reliably inserts a new <li> inside the right <ol>. Ask it to do the same in a Markdown list and you're at the mercy of indentation, blank lines, and whatever the surrounding context happens to be.
The verbosity that humans find tedious is the same verbosity that gives a model landmarks. Tags are self-describing, id and class attributes give the agent stable handles to target, and nothing is implicit.
Real wins I've seen
A few concrete examples from my own workflow:
- Surgical edits in long pages. "Update the third example in the Caching section" succeeds first try on an HTML doc. On the Markdown equivalent the model often touches the wrong heading, because it's counting
##instances. - Tables. Anything past three columns in Markdown is a coin flip. A
<table>with<thead>and<tbody>is boring, and it edits cleanly every time. - Code samples next to prose. HTML's
<pre><code>is unambiguous. Markdown code fences inside list items inside blockquotes are a parser's nightmare, and models hallucinate the number of backticks. - Diff review. A pull request that adds a
<li>is obvious. A pull request that adds a Markdown bullet sometimes re-indents the siblings too, and the reviewer can't tell whether that was intentional.
"But Markdown is what everyone uses"
It is, and that's fine for human-authored READMEs and short notes. Markdown was designed for humans typing plain text, not for a model performing structural edits at scale. If your docs site is mostly maintained by an AI agent, and increasingly mine is, optimise for the editor doing the work.
You don't lose much either. Most static site generators, including the one this blog runs on, render HTML inline quite happily. You can move file by file: keep the Markdown you have, and let any doc you ask an LLM to maintain live as .html.
My new rule of thumb
If a human writes it once, Markdown is fine. If an AI agent is going to keep editing it, write it in HTML. The verbosity pays for itself the first time the model lands a clean edit on a page you'd otherwise have had to fix by hand.
I'm not arguing HTML is more pleasant to write, because it isn't. I'm arguing that when your documentation is a living artifact maintained by tools that read tag structure better than they read whitespace, HTML is the format that keeps it correct.
If you want to test the claim, take your gnarliest doc, convert one long Markdown page to HTML, and run a week's worth of AI edits against both versions.
Update: this site now runs on HTML
Since writing this post I've migrated every blog post on this site from MDX to plain HTML, which felt like the least I could do. The content files live as .html in the repo and Next.js reads them at request time, with syntax highlighting and Mermaid diagrams handled at render time. Editing them with AI tools is noticeably smoother.