Skip to content

Documentation Site

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

Source of Truth

Item Location
Markdown source docs/ on main
MkDocs configuration mkdocs.yml
Published branch gh-pages
Publishing workflow .github/workflows/docs.yml
Public site https://docs.metricis.app/

The gh-pages branch is generated output. When documentation changes are merged to main, the Deploy docs GitHub Actions workflow installs MkDocs dependencies and runs:

mkdocs gh-deploy --strict --force

That command rebuilds the site, fails on MkDocs warnings, and force-publishes the generated HTML to gh-pages.

Local Preview

Install the same MkDocs packages used by CI:

python3 -m pip install mkdocs-material mkdocs-autorefs pymdown-extensions

Build the site:

python3 -m mkdocs build --strict

Serve a local preview:

python3 -m mkdocs serve

Then open http://127.0.0.1:8000/.

Update Workflow

  1. Edit Markdown files under docs/.
  2. If adding or moving a page, update mkdocs.yml.
  3. Build locally with python3 -m mkdocs build --strict.
  4. Open a PR and let CI pass.
  5. Merge to main.
  6. Confirm the Deploy docs workflow updates gh-pages.

Use the gh-pages branch only to verify generated output after deployment. Any manual edit there will be overwritten by the next docs deploy.

Archive Policy

Historical planning files under docs/archive/** remain in the repository for provenance, but they are excluded from the public MkDocs build. Source-only reference files that are intentionally kept outside the navigation are listed in mkdocs.yml under not_in_nav.

Strict MkDocs builds should remain clean. If a new warning appears, either fix the current documentation link, add the page to navigation, mark the source-only page in not_in_nav, or move superseded material under docs/archive/**.

Pages That Need Release Updates

When platform or deployment tooling changes, update these pages together:

Page Update Trigger
docs/index.md Current platform status, quick links, technology stack
docs/guides/deployment.md Production deployment, web release path, docs publishing
docs/guides/release-automation.md GitHub Actions + Fastlane workflow, secrets, release policy
docs/mobile-deployment.md Capacitor, Android, iOS, signing, debug/release commands
docs/getting-started/installation.md Local toolchain and ports
docs/guides/development.md Developer commands and environment variables
ROADMAP.md Milestone state and next operational gate

Current Tooling Baseline

The documentation site should reflect the current platform baseline:

  • Node 24.16.0 from .nvmrc
  • npm from the selected Node toolchain
  • Capacitor 8.3.x in client/package.json
  • Java 21 for Android builds
  • Android SDK 36
  • Android Gradle Plugin 8.13.0
  • Gradle wrapper 8.14.3
  • Fastlane lanes under fastlane/Fastfile
  • Release workflow under .github/workflows/mobile-release.yml