docs-preflight

docs-preflight

Run the project's strict docs build locally and report green/red before a docs commit lands. Strict mode is what CI runs — catching a broken cross- reference here costs ~20s; catching it in CI costs a wasted push and a red badge.

When this applies

The change touches any docs-affecting path: docs/**, mkdocs.yml, requirements-docs.txt, a Makefile docs target, conf.py, docusaurus.config.*, book.toml. If in doubt and a docs toolchain exists, run it — it's cheap.

Detect the toolchain, then run its strict build

Use the first match, top to bottom. A repo's own make target is preferred because it already encodes the venv and the correct strict flags.

1. Makefile docs target — grep -E '^docs-build:|^docs:' Makefile. If present, run make docs-build (or make docs). This is the common case for repos scaffolded from the operator's new-project template.
2. MkDocs — mkdocs.yml at repo root. Prefer the project venv:
   • .venv/bin/mkdocs build --strict --clean if .venv/bin/mkdocs exists
   • else python -m mkdocs build --strict --clean
3. Sphinx — docs/conf.py. sphinx-build -W -b html docs /tmp/_docs_preflight (-W promotes warnings to errors = strict).
4. Docusaurus / npm — package.json with a docs build script (docs:build, build:docs, or a docs workspace). Run that script; Docusaurus fails on broken links by default.
5. mdBook — book.toml. mdbook build.

If none match, say so — there is nothing to preflight. Do not invent a build.

Then lint the changed Markdown

A strict build does not check Markdown style, and a repo's commit hook or CI often does. When the repo has a markdownlint config (.markdownlint.json, .markdownlint.jsonc, .markdownlint.yaml, .markdownlint-cli2.*), lint the changed .md files with it:

env -u NODE_OPTIONS markdownlint --config .markdownlint.json <changed .md files>
# or, for a .markdownlint-cli2.* config:
env -u NODE_OPTIONS markdownlint-cli2 <changed .md files>