The docs at /inside/docs/ are static pages built by scripts/build_docs.py from markdown files in scripts/docs/<space>/. Four spaces are written by hand in the repository (Engineering, Observability, Research, FinOps); two come from the knowledge vault through scripts/import_vault_docs.py. A vault space can also hold hand-written pages: the SRE Handbook carries Principles in practice, written in the repository. A page is hand-written when its front matter has no origin line, in any space.
Build
python3 scripts/import_vault_docs.py ~/vault # vault spaces: sre, std (only on the machine with the vault)
python3 scripts/build_changelog.py # eng/changelog.md from closed issues and commits (needs the network)
python3 scripts/build_docs.py # all spaces, sitemap block, llms.txt section, docs search index
python3 scripts/build_inside.py # bar sync, services, status, the site-wide search indexThe build writes one index.html per page, inside/docs/search.json (an input to the site-wide index; see Top bar and search), a managed block in sitemap.xml and a managed section at the end of llms.txt. Then run the gate dry run and open a pull request as in CLAUDE.md.
Front matter
| Field | Use |
|---|---|
title, summary | Required. The summary is the meta description, the line in child-page lists and the search snippet |
parent | Slug of the parent page in the same space; empty means under the space home |
order | Sort key among siblings |
labels | Comma-separated; written as article:tag metas and shown as chips that open the search results for the label |
created, updated | Dates; without them the build uses the git date of the source file |
owner | Who keeps the page true. Required on hand-written pages; a vault page without one takes the space owner |
reviewed | The date the page was last checked against the system or source it describes, or no. For a hand-written page, the date it was written from the source counts as the first review. Vault pages start as no |
review_by | The date of the next review; 90 days after reviewed by default |
type | tutorial, how-to, reference or explanation (Diátaxis). A vault note keeps its own note type, mapped to one of the four where the mapping is plain (runbook to how-to, MOC to reference, position to explanation) |
origin | Vault pages only: the vault path. The import removes and rewrites only pages with this line |
state, source | Principle pages only (children of sre/principles-in-practice): in place, partial or gap, and the source of the principle as markdown links. The build stops when state differs from the bold word that opens the page's ## State section |
Ownership and review
The byline of each page shows the owner, the review date and the next review date, or "not reviewed", or "review overdue since" in red. Docs health lists the pages past their review date, those due in the next 30 days, pages without an owner or a type, and the counts per space. The build stops on a malformed date or an unknown type, and prints a warning for a hand-written page that lacks one of the four fields. Nothing here blocks a deploy: whether the gate should check owners and review dates is an open decision for the gate owner.
Decision records
A page with adr: N in its front matter is a numbered decision record under Decision records. It also carries status (proposed, accepted, superseded) and, when one record replaces another, supersedes on the new one and superseded_by on the old one. The build stops when the two sides disagree or two records share a number, and writes the index table where the parent page holds the marker <!-- adr-index -->.
Links
[text](doc:space/slug)links to another docs page; an unknown target stops the build.- Vault notes keep their wikilinks. A wikilink to a note in the export becomes a link; a link to a note outside it shows as plain text with a dotted underline.
- Every page lists the pages that link to it under "Linked from".
- A wikilink or a vault path resolves in this order: page titles, then aliases, then vault paths, then
space/slug. Within each, the exact spelling wins over a match that ignores case. The build prints a warning for two titles that differ only in case, and for an alias that equals another page's title or alias, because a link by that name reaches one of them only. Keep titles unique across all spaces, ignoring case. - Lists that sort by title (the tree, "Linked from", recent pages, docs health) break ties by URL, so two builds of the same sources write the same files.
Principle pages
The pages under Principles in practice tie each SRE principle to the platform. Two markers, each on a line of its own, are filled at build time:
<!-- principle-services -->on a principle page: the services whose YAML names the page underprinciples:(see Service catalog), as links.<!-- principle-index -->on the parent: a table of every principle with its source, state and services.
A principles: entry that names a page outside that section stops the build. The service page shows the same list under "SRE principles applied", so each link exists in both directions and the map records both.
In the map
Each page carries <meta name="docs-space">, article:tag metas, dates and <link rel="up"> to its parent. The map crawler turns those into doc nodes, tree links and labels, so the documentation is part of the map of the work.
Vault import rules (2026-10-09)
- In:
SRE/withouthomelab/,.claude/andCLAUDE.md; 28 standards clusters underpillars/. - Kept (since 2026-10-09): on each run the import removes only the files it wrote before, those with an
originline, and leaves hand-written pages inscripts/docs/sre/andscripts/docs/std/in place. A vault note whose slug equals a hand-written file name stops the import with an error; rename one of the two. Before this change the import deleted both folders. - Redacted: private IPv4 addresses and LAN shorthand, e-mail addresses, the former employer's name, home directory paths, private host names. Each change is listed in
scripts/docs/IMPORT-REPORT.md. - ISO clause notes: blockquotes are dropped unread, so no standards text is machine-processed.
- Every vault page carries a label: not reviewed against the source.
- An alias of a vault note that equals another page's title is dropped on import and listed in the report; the title keeps the name.