Visit djangoplay.org ↗
governance / Markdown standard
DocsGovernanceMarkdown standard

Markdown standard

How every doc in projects/ is written, so the site, the search and the version picker can rely on it. The same rules are enforced in code (build/content/standard.ts), so this page and the tooling c...

5 min readGovernance
On this page ▾
  1. 1. The header
  2. 2. Doc types
  3. 3. Body rules
  4. 4. Keeping a doc off the site
  5. 5. Commands
  6. 6. Checklist for a new doc

Audience: anyone who adds or edits a doc.

1. The header

Every doc starts with a frontmatter block. Five fields matter:

yaml
---
title: Restart the worker
description: How to restart the background worker without losing queued jobs.
type: runbook
since: 1.1.3
audience: user
---
Field Required Meaning
title yes The page title. It is the page's only h1: don't repeat it as # … in the body.
description yes One sentence on what the reader gets, under 200 characters. Shown under the title and in search results and link previews.
type yes What kind of doc this is (section 2). Decides the body template.
since yes, in a versioned project The version the doc first appeared in. See VERSIONING.md.
audience no, default user internal keeps the doc in the repo but off the public site (section 4).

Optional: order (sort position in the sidebar), updated (YYYY-MM-DD; the git date is used when absent), changed, deprecated, removed (version lifecycle), draft: true (not built at all).

A header may still be missing a field on an older doc: the build then falls back to the doc's first heading and first paragraph and prints a warning. If the body also opens with the same heading or paragraph as the header, the site shows it once.

2. Doc types

type Use it for Usual folder Template
overview A project's README or a section landing page project root templates/overview.md
guide A task a reader does: install, configure, use user-guide/ templates/guide.md
reference Facts to look up: options, settings, limits reference/ or user-guide/ templates/reference.md
architecture How the system is built and why architecture/ templates/architecture.md (system-design.md for a whole system)
api Endpoints, requests, responses, errors api/ templates/api.md
runbook What to do when something happens runbooks/ templates/runbook.md
deployment How to build, ship and roll back deployment/ templates/deployment.md
release-notes One release releases/ templates/release-notes.md
changelog The running list of changes (usually generated) changelog/ templates/changelog.md
adr One architectural decision adr/ or architecture/ templates/adr.md

3. Body rules

  • No # Title line: the header's title is the h1. Start with the content.
  • Use ## for sections and don't skip levels (## then ####).
  • Use placeholders for anything sensitive: <domain>, <secret_key>, <db_password>.
  • Link other docs with relative paths (../runbooks/restart.md); the build fails on a broken link or image.
  • Delete the <!-- template: … --> comment a template starts with.
  • File names are lowercase with hyphens (release-signing.md); README.md is the landing page of its folder.

npm run docs:check reports heading jumps, extra h1s and leftover template comments as advice.

4. Keeping a doc off the site

Put audience: internal in the header. The doc stays in the repo, next to the code it documents, but isn't built, listed, searched or in the sitemap. A link to it from a public doc is a broken link, so the build tells you.

A whole folder can be marked internal in project.json (docsRoots with audience: internal); that folder rule wins over a doc saying user. The old skip list (build/skip.ts) is now empty and only for dropping a whole folder or project that has no headers.

5. Commands

bash
npm run new:doc                  # asks for project, type, title, description; writes the doc from its template
npm run new:doc -- gitaiflow runbook "Rotate the signing key" --desc "Steps to rotate the release signing key."

npm run docs:check               # every doc against this standard (fast; no bundling)
npm run docs:check -- --report   # ...and write docs-report.md: one file, every doc, where to add what
npm run docs:check -- --strict   # exit 1 on any header problem (CI)

npm run docs:fix                 # dry run: fill missing header fields from what each doc says
npm run docs:fix -- --write      # apply (then review with git diff)

npm run check-content            # the full content check: header warnings plus links, dates, versions

new:doc puts the doc in the type's usual folder, names the file after the title, and sets since to the project's current version. It refuses to write a doc into a folder that isn't in the project's categories (the doc wouldn't be published) or over an existing file.

docs:fix never changes a field that already exists and never reformats existing lines. The title and description it writes are taken from the doc's own heading and first paragraph, so read the diff before committing.

6. Checklist for a new doc

  1. npm run new:doc (or copy a template and fill the header).
  2. Write the doc; delete the template comment.
  3. npm run docs:check -- --project <slug> reports nothing for it.
  4. npm run build passes (links and anchors resolve).