Process Publishing¶

Everything under docs/ publishes to the support microsite private section.

Rules¶

Treat the docs/ tree as the canonical authored source.
Publish the docs/ tree to the support microsite private section.
Do not create a second source of truth while publishing.
Product manual folders under docs/products/*/user-manual/ are generated read-only mirrors. Update the source product repo, then let ./wiki sync rebuild the mirror.
When adding, renaming, or moving a BFDev docs page, update the relevant section index.md pages so the page remains discoverable.
Treat broken navigation, orphaned pages, failed ontology validation, or broken internal links as incomplete documentation work.

Run ./wiki validate before publishing or merging structural docs changes.
./wiki validate and ./wiki serve refresh product manual mirrors before validation or serving.
Maintainers publish locally with ./wiki publish <support-root>, which validates the docs tree, builds the MkDocs site, and stages the generated output into the checked-out bf-support-microsite repo under public/private/bf-dev/.

BFDev CI owns the automated sync in .gitlab/docs-publish.yml.
The docs validation job runs for docs changes in CI and must pass before publication is considered healthy.
The publish job clones support-microsite, runs uv run python -m docs_management publish, and pushes the updated generated docs when there is a diff on the default branch.
bf-support-microsite serves the published output; it is the serving target, not the canonical authored source.