Documentation Standard

Canonical Location

Durable, human-authored documentation lives under docs/src/content/docs/. Service-local README files may contain setup notes and pointers, but canonical explanations belong in this docs site.

Page Metadata

Every canonical human-authored page must include frontmatter with these fields:

title
status
owner
domains
doc_type
last_reviewed
related_code

Use related_docs when a page depends on an ADR, standard, flow, generated reference, or another canonical page.

Status Values

Normal documentation status values:

draft
active
needs-review
deprecated

ADR status values:

proposed
accepted
superseded

Document Types

Supported doc_type values:

overview
architecture
service
flow
adr
standard
operation
runbook
generated-index

Source Linking

Every durable factual claim should link to source code, configuration, generated references, an ADR, or another canonical page where practical. Use related_code for the authoritative code paths and inline links for the exact evidence readers need.

Diagrams

Use Mermaid for diagrams by default. Use checked-in SVG or PNG assets when Mermaid cannot express the diagram clearly.

Shared assets live under docs/src/content/docs/_assets/ or docs/public/assets/ depending on whether the asset is content-specific or globally served.

Page-specific assets live beside the page in an _assets/ folder.

Generated References

Generated docs stay in the paths where generation tools write them. Canonical docs should index generated references and explain how to regenerate them. Do not hand-edit generated docs.

Service-Local Docs

After migration, service-local docs should point to canonical docs. They should not duplicate architecture, flows, standards, or decisions.

Deployment And Secrets

The internal docs site is built from docs/ and deployed behind Cloudflare Access. Do not put secrets, live DSNs, bearer tokens, or credentials in docs.