Not every repo doc belongs in Markdown

Your team spent two weeks on the plan to roll AI agents out across three squads. Owners, risks, a budget ask, and a go or no-go decision the VP has to sign. It lives in the shared code repository, so somebody saved it as a plain-text file, plan.md. The VP opens it, scrolls through six hundred lines of headings and bullets, and writes back: "let's discuss in the next meeting."

The plan didn't fail because it was wrong. It failed because nobody could read it to a decision. The content was all there. The medium buried it.

My position: markdown is the default for repo docs because it is a great source format. That is not the same as being a good reading format. The moment a document's job is to get a human to decide, the format you wrote it in becomes part of whether they can.

Source and artifact are two different jobs

There is a distinction most teams collapse: the format you write in and the format someone reads do not have to be the same thing.

A source format is built for the people and tools that produce and maintain a document. It diffs cleanly, it reviews in a pull request, an agent can ingest it, an engineer can read it without opening a browser. Markdown is close to perfect at this. That is why it became the default, and it earns the default.

A reading format is built for the person consuming the document, once, to make a judgment. It has a hierarchy that tells the eye what matters most. It has a reading order. The decision is the thing you land on, not the fourteenth bullet under the fourth heading.

Most repo docs only need the first job. A README orients a developer. A runbook helps an operator recover. An agent rule has to be short enough that a model doesn't skim past the invariant. Markdown is excellent for every one of those, because the reader is technical, the document is reference, and raw source is a fine way to read it.

The trouble starts with the docs that have the other job.

Markdown told you what it is, and so did GitHub

Go back to what Markdown was for. John Gruber, who created Markdown, was explicit about the job it does:

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML.

Read that again. Markdown was never the reading format. It was always the source, and HTML was the thing the reader got. The conversion is the whole point.

GitHub, which did more than anyone to make .md the universal repo language, draws the same boundary in its own tooling. When it renders your Markdown, the HTML is sanitized, aggressively removing things like script tags, inline styles, and class or id attributes. That is GitHub refusing to let every README pretend to be a website. The platform that normalized Markdown everywhere deliberately caps how much reading experience you can wring out of it. If you find yourself fighting the sanitizer to make a doc look right, the doc is telling you it wanted to be an artifact, not a README.

The same plan, as something a human can approve

Take the adoption plan back and change nothing about its content. Same owners, same risks, same budget, same decision. Change only the medium.

Now the status of each workstream is something the eye catches in one pass, not a word buried in a sentence. The risk table scrolls inside its own container instead of wrapping into noise. The one thing that needs a signature is visually the loudest thing on the page. The assumptions the VP is actually approving sit in their own block, not interleaved with implementation notes meant for an engineer.

The VP approves it in four minutes, because for the first time the document does the one job it existed to do: produce a decision.

Notice what did not happen. Nobody threw Markdown away. The plan's source can still be plain text in the repo, reviewed in a pull request, diffed line by line. What changed is that the reading surface stopped being raw source. That is the entire move: keep the source format, and stop forcing it to also be the reading format.

If you are fighting Markdown to make a document approvable, you don't have a writing problem. You have a doc doing a job its format was never built for.

"But everything should be plain text in git"

Here is the strongest objection, and it is a good one. The docs-as-code movement, well described by Write the Docs, argues you should write documentation with the same tools as code: version control, plain-text markup, code review, automated tests. A purist reads that as: so every doc is Markdown, end of discussion. Adding a second rendering path is tool sprawl, a second frontend nobody asked for.

I take that seriously, because the cost is real. A standalone HTML artifact is more expensive to review, diff, and maintain than a .md file. Reach for it casually and you create exactly the mess the objection warns about.

But docs-as-code is a claim about the workflow, not about the reading surface. Source in git, reviewed, tested. None of that requires the reader to consume raw source. The mature docs systems prove it: the Rust book is authored in Markdown and rendered into a navigable book by mdBook, which literally describes itself as a way to create a book from Markdown files. MDX, Docusaurus, and tools like them exist precisely to keep a plain-text reviewed source and still ship a real reading artifact. Source versus artifact is not a violation of docs-as-code. It is docs-as-code carried all the way through.

There is even a performance reason to keep the two separate, and it is not "HTML fast, Markdown slow." The real question is where the Markdown-to-HTML conversion happens. Do it once, ahead of time, the way Next.js static generation builds the HTML before the request arrives, and the reader pays nothing for it. Do it on every page view, in the server or worse in the reader's browser, and you have moved documentation work into user traffic. Cheap source can quietly become expensive reading.

The rule I use now

I would not put HTML everywhere. That is the second-frontend trap, and the objection is right about it. The rule is about jobs, not formats.

Keep Markdown as the source and the reading surface for anything whose reader is a machine, a developer, or a code review:

• READMEs, agent rules, and tool configs.
• durable specs, ADRs, runbooks, and concept docs.
• anything an agent ingests or an engineer reads as reference.

Render a human-facing artifact when the reader is a person making a judgment and the reading experience is the deliverable:

• plans and strategy briefs a stakeholder has to approve.
• executive and client-facing reports.
• visual QA reports and design artifacts.

And one constraint is non-negotiable: the artifact has to be semantic and accessible, not a pretty pile of nested boxes. MDN's accessibility guidance is the boring receipt here, real headings, labels, link text, and keyboard-reachable structure. A semantic artifact that a screen reader can navigate is the deliverable. An inaccessible one is just a PDF with extra steps.

This matters more as teams go AI-native, not less. Agents generate more docs, not fewer. Every run wants context, every plan wants acceptance criteria, every review wants evidence, every handoff wants a snapshot. The cheap move is to dump all of it into Markdown because Markdown is cheap to produce. But the loop AI-native work actually runs on is: a machine drafts, a human decides, a machine acts, a human verifies. The two human steps are reading steps. If every one of them is a wall of raw source, you optimized for the writer and taxed the decider.

Markdown is a source format. Ask it to be the source and it is the best tool you have. Ask it to also be the artifact a human signs, and you are using a screwdriver as a hammer. It works, right up until the day the decision actually matters.