docs-site

name	docs-site
description	Rules for the published MkDocs site under docs/ - nav entries, relative links, heading anchors, analytics gating, and local preview. Use when adding, renaming, moving or linking a page under docs/, or when touching .github/mkdocs.yml, the docs workflow or its hooks.

docs/ is published, so a broken link is a build failure

docs/ ships to https://athrvk.github.io/vayu/ via MkDocs Material (.github/mkdocs.yml, .github/workflows/docs.yml, deps pinned in requirements-docs.txt). mkdocs build --strict runs on every docs-touching pull request and fails on an unresolvable relative .md link or a missing heading anchor, so:

• Add a new page to the nav: in .github/mkdocs.yml in the same commit. Off-nav pages build and are reachable by URL, but never appear in the sidebar.
• Do not rename or move a doc file without checking for readers. Tests read doc paths (app/src/design-system-doc.test.ts reads docs/design-system.md; app/src/state-management-doc.test.ts reads docs/app/state-management.md, architecture.md and api-integration.md, and fails on a useXxx or SCREAMING_CASE name they quote that no longer exists in the app source), and every relative cross-link is validated by the build.
• Anchors follow GitHub's slug rules (pymdownx.slugs.slugify is configured for exactly this), so one anchor form works both in GitHub's markdown view and on the site. Heading punctuation counts: ## Shared Auth Fields (components/shared/AuthFields/) is #shared-auth-fields-componentssharedauthfields.
• Links out of docs/ (SECURITY.md, LICENSE, CONTRIBUTING.md) must be absolute https://github.com/athrvk/vayu/blob/master/... URLs - those files are outside the published tree.
• Analytics is on the published site only, and only when it has an ID. The GA4 measurement ID comes from the GOOGLE_ANALYTICS_KEY Actions repository variable (Settings -> Secrets and variables -> Actions -> Variables), read by extra.analytics.property via !ENV. With it unset - every fork, every pull-request preview, every local mkdocs serve - .github/hooks/analytics.py strips extra.analytics, extra.consent and the footer's "Cookie settings" link, so those builds ship no tracker and no banner. !ENV alone does not do this: Material emits its gtag snippet even for an empty property, which is the whole reason that hook exists. On the published site GA is consent-gated - the snippet is defined but only runs once the visitor accepts. This is the docs website, not the app; no telemetry in docs/index.md and README.md is a claim about the app and stays true, so keep the two apart when editing either.
• Jekyll is not an option here and the workflow says why: Pages' default Jekyll build runs Liquid over page content, and these docs contain 40+ {{variable}} examples (rendered as empty strings) plus {% ... %} (an unknown tag, which fails the build). MkDocs never templates page content.

Preview locally with pip install -r requirements-docs.txt && mkdocs serve -f .github/mkdocs.yml. The -f is required - the config is not at the repo root - and the site serves under /vayu/. The favicon/logo are not files under docs/: .github/hooks/brand_assets.py pulls shared/icon_png/vayu_icon_256x256.png into the build, so do not add a copy.

install.sh at the repo root is also published at the site root by .github/hooks/install_script.py, which is why it appears in the paths: filters of docs.yml.