Skip to content

Docs CI (strict)

.forgejo/workflows/docs.yml gates every PR that touches docs/** or mkdocs.yml. Per ADR 0003, this is deliberately strict: a broken internal link, a broken nav entry, or an invalid Mermaid diagram is doc drift, and drift left unchecked is silent failure -- so it fails the PR like any other red check, not a warning someone eventually notices.

The job always triggers (no path filter at the workflow level) but skips straight to green for any PR that doesn't touch docs -- see the comment at the top of the workflow file for why (ARGUS-161: a path-filtered trigger on a required status check permanently blocks unrelated PRs from merging).

Three checks, in order

  1. markdownlint (markdownlint-cli2, config in .markdownlint.yml, pinned version) -- catches malformed Markdown: missing fenced-code language, ambiguous list/emphasis syntax, accidental duplicate/multiple titles. .markdownlint.yml documents inline why MD013 (line-length), MD034 (bare URLs), and MD025 (single top-level heading) are tuned off or scoped for this corpus rather than left default -- read the comment block at the top of that file before changing a rule.
  2. mkdocs build --strict -- fails on a broken nav entry or a broken internal link (mkdocs.yml's validation.nav.not_found and validation.links.not_found are warn, which --strict promotes to a hard error).
  3. Mermaid validation (scripts/check-mermaid.py) -- extracts every fenced ```mermaid block from every file under docs/ and compiles each one with mermaid-cli (mmdc, pinned version). A parse error is reported as path:line: message, where line is the block's real position in the source file, not an offset into the extracted snippet.

Running it locally

python3 -m venv .venv-docs && source .venv-docs/bin/activate
pip install -r requirements-docs.txt
npx --yes markdownlint-cli2@0.13.0 "docs/**/*.md"
mkdocs build --strict

The Mermaid step needs a Chromium binary mermaid-cli can drive headlessly; CI installs one via apt-get install chromium and points PUPPETEER_EXECUTABLE_PATH at it (see the workflow's "Bootstrap" and "Mermaid validation" steps) rather than letting npm install download its own -- faster, and it reuses the Chromium apt already resolved.