Documentation Site¶

Metricis documentation is published from source in this repository. Do not edit generated HTML or the gh-pages branch directly.

Sources and destinations¶

Item	Location
Public Markdown source	`docs/` on `main`
Canonical positioning/status	`docs/capabilities.json`
MkDocs configuration	`mkdocs.yml`
Pinned Python dependencies	`docs/requirements.txt`
Validation/deploy workflow	`.github/workflows/docs.yml`
Published branch	`gh-pages`
Public site	`https://docs.metricis.app/`

The local site/ directory is generated output and is ignored. GitHub Pages output is recreated by mkdocs gh-deploy --strict --force after validation succeeds on main.

Public and internal boundaries¶

Public documentation explains the platform contract, status, workflows, architecture, APIs, and operations. Historical plans, active implementation plans, design working notes, consent templates, and obsolete references remain repository material but are excluded through exclude_docs in mkdocs.yml. Excluded pages are not built, searched, or published.

Use not_in_nav only for current source documents that should still build but intentionally lack navigation. Do not use it to hide stale planning content: not_in_nav pages can still be published and indexed.

Canonical product claims¶

docs/capabilities.json owns:

the short platform description;
landing headline and summary;
capability labels and summaries;
availability definitions; and
the last verification date.

The landing page imports that manifest directly. README, MkDocs metadata, and the docs home repeat the canonical short description and are checked by scripts/check_docs_drift.py.

When a capability changes, update the manifest, public capability page, relevant workflow page, and ROADMAP milestone in the same documentation change. Do not label a capability “available” merely because code exists behind a gate or requires unconfigured infrastructure.

Local validation¶

Install exactly the versions used in CI:

python3 -m pip install -r docs/requirements.txt

Run the claim/drift check and strict build:

python3 scripts/check_docs_drift.py
python3 -m mkdocs build --strict --site-dir /tmp/metricis-docs

For an interactive preview:

python3 -m mkdocs serve

Then open http://127.0.0.1:8000/.

Landing-page changes additionally require:

pnpm run build:landing

Pull request and deployment flow¶

Edit public Markdown, the capability manifest, metadata, or landing copy.
Update mkdocs.yml when a page is added, moved, excluded, or added to navigation.
Run the drift check and strict MkDocs build locally.
Build the landing site when shared claims or landing files changed.
Open a pull request. The Documentation workflow validates relevant changes without write permission.
Merge only after validation succeeds.
The deploy job rebuilds and publishes gh-pages with write permission only on main or a manual dispatch.
Verify the workflow, https://docs.metricis.app/, and any changed navigation or metadata after publication.

If GitHub Actions is blocked by an account spending limit, local validation does not prove publication. Resolve the account gate, rerun the workflow, and verify the live site before declaring deployment complete.

Drift review cadence¶

Review the capability manifest and public headline at every milestone that changes a user-visible capability or gate. At minimum, audit them before a tagged release and when the roadmap's current-state summary materially changes.

The documentation workflow intentionally watches public docs, landing copy, README/package metadata, mkdocs.yml, its own workflow file, and the drift-check script. Landing deployment watches landing source, the capability manifest, package metadata, the lockfile, and the drift-check script; it validates claims before building.