Not every repo doc belongs in Markdown

Most teams do not have a documentation problem. They have a reader-experience problem hiding inside a Git workflow.

Markdown became the default for good reasons. John Gruber described it as an easy-to-read, easy-to-write plain text format that converts to structurally valid HTML in the original Markdown project page: original Markdown project page. That is still the best argument for Markdown: it is source text. It diffs well. Agents can ingest it. Engineers can review it without opening a browser. It fits the docs-as-code model that Write the Docs describes: version control, plain-text markup, code review, and automated checks: Docs as Code guide.

But source format and reading format are not the same thing.

That distinction gets lost inside repositories. The team writes an implementation plan, an architecture report, a stakeholder review, a launch brief, a QA artifact, or a prototype explanation. The file lives in git, so somebody reaches for .md. Then the doc becomes a scroll of headings, bullets, and tables that technically contains the answer but does not make the answer legible.

That is when HTML/CSS is not decoration. It is the medium.

GitHub already tells you where the boundary is

GitHub's repo surfaces are optimized for Markdown. README files are automatically displayed on repository pages according to GitHub Docs: GitHub Docs. GitHub Flavored Markdown gives teams tables, task lists, autolinks, and code fences. That is the right shape for source docs.

But GitHub also deliberately limits arbitrary visual control in rendered Markdown. The github/markup README says GitHub sanitizes rendered HTML, removing things like script tags, inline styles, and class or id attributes: github/markup README. The GitHub Flavored Markdown spec documents a Disallowed Raw HTML extension: GitHub Flavored Markdown spec. That is not GitHub being annoying. It is GitHub refusing to let every README become a tiny unsafe website.

If the goal is source readability, use Markdown. If the goal is visual fidelity, README.md is the wrong place to fake a website.

GitHub Pages exists for the second case: static HTML, CSS, and JavaScript straight from a repository, optionally through a build process, published as a website: GitHub Pages docs. Docusaurus, MDX, mdBook, Sphinx, rustdoc, and similar systems exist for the same reason. Serious docs often keep source close to code, then render a richer human artifact.

Markdown is great until the doc has a different job

A README has a job: orient a developer.

A runbook has a job: help an operator recover.

An agent rule has a job: be short enough that a model does not skim past the invariant.

Markdown is excellent for those.

But some repo docs have a different job. They need to persuade, brief, compare, or create shared judgment across people who will not read a raw diff. An AI adoption plan is not just text. It needs assumptions, status, owners, risks, evidence, and a reading order. An architecture review needs hierarchy. A QA report needs receipts the reader can scan. A launch brief needs the eye to land on the decision, not on another ornamental bullet.

You can force all of that into Markdown. Teams do it every day. It works in the same way a spreadsheet can be a CRM. You can, but the medium is fighting you.

HTML/CSS gives the artifact a reading order

HTML/CSS lets the artifact say: this section matters more, this is metadata, this is the decision, this is a receipt, this table can scroll, this warning is not another bullet, this doc is meant to be opened by a human.

AI-assisted workflows tend to create more repo artifacts: plans, audits, review notes, handoff summaries, prototype briefs. Markdown keeps those files cheap to create. It does not automatically make them cheap to approve.

That distinction matters because repo docs are no longer only written by humans for other engineers. They are increasingly part of an operating loop: an agent drafts, a human decides, another agent acts, and a human verifies. The human verification step cannot be a wall of Markdown every time.

The internet debate is not Markdown versus HTML

The useful version of the debate is simpler: source versus artifact.

The best examples do not throw Markdown away. The Rust Book is authored in a repo and rendered as a navigable HTML book; mdBook describes itself as a command-line tool that creates books with Markdown and provides a clean, navigable, customizable presentation: mdBook docs. Docusaurus tells writers to focus on content and write Markdown files, then gives them a documentation website with versioning, i18n, search, React, and MDX: Docusaurus docs. MDX calls itself Markdown for the component era because sometimes prose needs components: MDX docs.

Even the anti-Markdown arguments are really anti-weak-semantics arguments. Eric Holscher's 2016 critique points at Markdown's flavors and limits for technical documentation: Eric Holscher critique. CommonMark exists because Markdown needed a stronger, more compatible specification: CommonMark. Google still frames Markdown as the preferred default for developer docs and treats HTML as the exception when Markdown cannot express the structure: Google Markdown guidance.

• Markdown wins when the source text must stay simple, reviewable, portable, grep-friendly, and friendly to agents or code review.
• HTML/CSS wins when the reader experience is the deliverable: hierarchy, layout, scanning, navigation, and visual fidelity change comprehension.
• MDX or generators win when you need both source review and a maintained docs product, and can shift parse cost to build time instead of every reader.

Standalone HTML is not a new default. It costs more to review, diff, lint, and maintain. If the doc changes often, keep a Markdown or MDX source and generate the reading artifact. Use standalone HTML/CSS when the output is bounded, human-facing, and read more often than it is edited.

Performance is mostly about where parsing happens

There is also a computational version of this argument. It is not "HTML fast, Markdown slow." That is too sloppy.

The better question is: where does the conversion happen? Browsers render HTML and CSS natively. Markdown has to become HTML somewhere before the reader gets a normal web page. That work can happen at build time, at request time, or in the browser.

Build time is usually the clean path. Next.js describes Static Generation as HTML generated at build time and reused on each request, with CDN caching available: Next.js Static Generation docs. That is the same pattern behind a lot of documentation tooling: write Markdown or MDX as source, compile it once, ship static HTML/CSS as the artifact.

Request time is where the cost starts to matter. If every page view asks the server to load Markdown, parse it, transform it, sanitize it, syntax-highlight it, and render HTML, you moved documentation work into user traffic. Next.js's server-side rendering docs make the contrast plain: SSR generates HTML on each request rather than once at build: Next.js server-side rendering docs.

Browser time is the most suspicious path. Client-side Markdown means shipping a parser to the user and spending their CPU to turn text into DOM. Libraries like Marked and markdown-it advertise speed and maintain benchmark suites because parsing Markdown is real work: Marked and markdown-it. MDX adds another layer: the package docs describe compilation to JavaScript through @mdx-js/mdx: @mdx-js/mdx package docs.

The performance rule is simple: keep Markdown cheap as source, but do not make every reader pay the Markdown-to-HTML tax at runtime.

Static HTML/CSS is not magically lighter if you bloat it with framework JavaScript, giant fonts, client hydration, analytics noise, or uncompressed assets. But a semantic standalone HTML artifact has a very boring delivery path: serve file, parse native HTML, apply CSS, cache hard. That boring path is the point.

My rule for repos now

I would not put HTML everywhere. That is how you create a second frontend nobody asked for.

Keep Markdown for:

• README files.
• AGENTS.md and tool rules.
• durable specs, ADRs, runbooks, and concepts.
• anything whose primary consumer is an engineer, an agent, grep, or a code review.

Use standalone HTML/CSS for:

• human-facing plans.
• executive or stakeholder reports.
• visual QA reports.
• prototypes and design artifacts.
• strategy briefs where layout changes comprehension.

And make one constraint non-negotiable: the HTML artifact must be semantic and verified. MDN's accessibility guidance is the boring receipt here: use the right HTML elements, labels, link text, headings, tables, and keyboard-friendly structure: MDN accessibility guidance. A pretty inaccessible artifact is just a PDF with extra steps.

Why this matters for AI-native teams

AI pushes teams toward more documentation, not less.

Every agent run wants context. Every plan wants acceptance criteria. Every review wants evidence. Every handoff wants a snapshot. The temptation is to dump all of it into Markdown because Markdown is cheap.

Cheap source can become expensive reading.

A repo that treats every doc as .md optimizes for writers and agents. A repo that separates source docs from human artifacts optimizes for the full loop: machine reads, human decides, machine acts, human verifies.

That is harness engineering in miniature. Not process for its own sake. A boundary.

Markdown is where the repo remembers.

HTML/CSS is where the repo explains.

Use both. The trick is not asking one file format to do both jobs.