Markdown for documentation

Markdown became the default format for technical documentation because it lets docs live in the repository, change in the same pull request as the code, and get reviewed by people rather than by nobody. The syntax is the easy part — what follows is the structure and the conventions that decide whether a docs folder stays usable at fifty files.

The actual argument for it

It is not that Markdown is pleasant to write, though it is. It is that plain text in version control makes documentation reviewable.

A wiki page is edited somewhere else, by someone else, at some other time. That is three chances for it not to happen. A Markdown file in the same repository can be changed in the same pull request that changed the behaviour, and a reviewer who notices the code change but no doc change can say so before it merges.

Everything else follows from that: diffs that show which sentence changed, history that says who wrote a claim and when, and the ability to require a doc update the way you require a test.

Four kinds of page, and why mixing them hurts

The most common structural failure is a single page trying to teach, instruct, specify and explain at once. Those are four jobs with four shapes:

A page that starts as a how-to and drifts into explanation loses the reader who came to do the task, and never satisfies the one who came to understand. Split it, and link between them.

What to standardise

Four conventions do most of the work of making a folder of files feel like one document. The rest can be left to taste.

• One # per file, and start at ## below it. Skipping from # to ### breaks the outline a generated contents list and a screen reader both rely on.
• A fixed front matter shape. Decide which keys are required — usually title and description — and check it in CI. Front matter that varies per file cannot be used for anything.
• Relative links between documents, including the .md extension. They work in the rendered site, in the repository browser, and in an editor's go-to-definition.
• One line-wrap rule. Either wrap at a column or put one sentence per line — both diff well. What does not work is mixing them, which turns every edit into a reflow that hides the real change.

A formatter settles the rest without a style argument: consistent bullets, renumbered lists, normalised spacing.

Front matter earns its place here

The YAML block at the top of the demo above is how a static site generator learns a page's title, description, ordering and audience without you repeating them in the prose.

---
title: Rotating an API key
description: Replace a key without downtime.
audience: operators
---

Keep the required keys to the two or three you actually use, and validate them in CI. A key that is optional in practice will be missing in half the files within a year, which means nothing can depend on it. Details on the front matter page.

Publishing it

All the common generators read the same Markdown, so this choice is reversible and not worth a long meeting:

That last row is worth taking seriously for a small project. GitHub renders Markdown, resolves relative links and provides search. A generator earns its keep at the point you need versioning, custom navigation or a domain of your own.

Keeping it honest

• Docs change in the same pull request as the behaviour. This is the whole mechanism. Everything else is compensation for not doing it.
• Link-check in CI. Relative links break silently when a file moves, and a docs site full of dead links teaches readers not to click.
• Give each page an owner in front matter or a CODEOWNERS file, so a review request has somewhere to go.
• Delete aggressively. A page describing a removed feature is worse than a missing page, because the reader believes it.

Where Markdown runs out

It has no cross-references, no includes, no conditional content and no variables. Generators add these as extensions, and every extension you use is a file that no longer renders correctly on GitHub or in an editor.

That trade is usually worth making for a real docs site and rarely worth making for a docs/ folder. If you find yourself needing all of them, the honest answer may be reStructuredText or AsciiDoc rather than Markdown with six plugins.