Skip to content

Documentation site

This documentation is built from docs/ and published to the sites site in the docs space on the ECMWF Sites instance. The pipeline is utilities/release/build_publish_docs.sh (called by make build-docs and make publish-docs), staged by utilities/release/docs_stage.py, and configured by utilities/release/docs/zensical.toml.

Build stages

  1. docs_stage.py copies docs/ to a staging directory. It rewrites every relative link that leaves docs/ into a GitHub URL under https://github.com/ecmwf/ecmwf-sites/tree|blob/<ref>/, where <ref> is the DOCS_SOURCE_REF value (default main). Links that point outside the repository, or at a repository path that does not exist, fail the stage step with does not point to a file in the repository. The build never publishes a page set with a dangling repository link.
  2. The script copies zensical.toml next to the staged pages and runs Zensical with build --clean --strict --config-file. The strict build fails on broken internal links.
  3. make publish-docs uploads the generated HTML with sitesctl site --space <space> --name <site> content upload using separate CLI settings, the token from the environment, --force (overwrite), and no deletion of other content.

zensical.toml lists the site navigation explicitly: every page under docs/ must appear in nav, and every nav entry must exist on disk. make build-docs enforces both directions through its check-docs-nav prerequisite, so a split or renamed page cannot silently drop out of the navigation. The strict build also aborts on broken internal links and anchors. A page larger than about 350 lines is split into a directory with an index.md and sub-pages, which keeps the parent URL unchanged.

Environment overrides

Variable Mode Effect
DOCS_OUTPUT_DIR build and publish HTML output directory (default dist/docs)
DOCS_SOURCE_REF build and publish Git ref used in rewritten repository links (default main)
ZENSICAL build Full command that runs Zensical (default uv run --only-group docs zensical)
SITESCTL publish sitesctl command name or path (default sitesctl)
DOCS_BASE_URL publish (required) https:// URL of the destination platform
DOCS_TOKEN publish (required) Token with write access to the destination site
DOCS_SPACE, DOCS_SITE publish Destination space and site (default docs, sites)

Publishing

The Publish workflow runs make publish-docs in the publish-docs job (see Releases). It installs a fixed sitesctl build (SITESCTL_VERSION, currently 20260817.0745) from get.ecmwf.int, and verifies its SHA-256 (SITESCTL_SHA256) before uploading, and sets DOCS_SOURCE_REF to the release tag, so links to repository files point at the tagged source. All releases share one documentation site; re-publishing an older tag replaces the pages with the same names. The publish-docs concurrency group serialises uploads.

The CI workflow runs make build-docs on every push and pull request, so the same strict build fails a change before a release, and the Publish workflow does not publish a page set that does not build.

Complementary guides for the Sites CLI and the Sites SDK are uploaded to /docs/sites/cli/ and /docs/sites/sdk/ by their own repositories; the nav references them as site-root paths.

Page rules

  • Every file under docs/ starts with the SPDX header block that REUSE.toml expects; new pages copy the header from an existing page.
  • Design documents end with a behaviour requirements table (see design README); the index.md of a split set carries the table for the whole set.
  • Check rendering and links locally before opening a pull request; the CI and Publish workflows run the same strict build:
make build-docs