Native documentation platform¶
docs-sites.toml is the machine-readable contract for the six repositories
that make up the native HSSM documentation platform. It records what is live,
what is being adopted, the shared toolchain, the build interface, and the
workflow and brand distribution destinations. Its site_url values also own
the canonical targets for each repository's GitHub About website link. The
manifest owns the common top-level navigation; page groupings and content
beneath it remain repository-owned.
Sites and adoption state¶
| Repository | Profile | Current state | Documentation root |
|---|---|---|---|
| HSSM | library | live | docs/ |
| ssm-simulators | library | live | docs/ |
| LANfactory | library | live | docs/ |
| LAN_pipeline_minimal | operational | live | docs/ |
| HSSMCortex | operational | live | docs/ |
| HSSMSpine | orchestration | live | _docs/ |
state describes adoption of this documentation contract, not package
maturity. This table reflects the 2026-08-24 closeout; docs-sites.toml is the
authoritative current source. Manifest consumers operate on live sites by
default. A planned site becomes live only after its native docs build, caller
workflow, and published URL are working; tools may target a planned site
explicitly during that migration.
For every live site, the repository homepage metadata points to the exact
manifest site_url. GitHub renders that setting as the Website link in the
repository's About panel. The monthly docs-quality audit checks this live
metadata read-only; it does not change repository settings automatically or
make GitHub API access a pull-request build requirement.
Profiles make the quality rubric proportional to the site:
librarysites teach and reference a public Python API.operationalsites teach a runnable system, its configuration, and its operating procedures; an exhaustive Python API is not inherently required.orchestrationsites explain cross-repository policy and workflows; their reference surface is contracts, manifests, and contributor procedures.
Canonical navigation¶
Every native site exposes these top-level sections in this exact order and
with these exact labels: Home, Learn, How-to guides, Explanations, and
Reference. Profiles change what belongs beneath a section, not its label or
position. Additional material such as contributing guidance is nested under
the appropriate canonical section instead of creating another top-level
section.
Every site uses Material for MkDocs and enables the built-in search plugin.
Repositories may add profile-specific plugins, but they may not remove search.
MkDocs validation sets omitted_files, absolute_links,
unrecognized_links, and anchors to warn; strict builds promote any of
those warnings to failures.
Pinned toolchain¶
Every native site uses Python 3.12 and uv 0.12.2. The shared documentation
dependency pins are MkDocs 1.6.1, Material for MkDocs 9.7.7,
mkdocs-redirects 1.2.2, mkdocs-autorefs 1.4.4, mkdocs-jupyter 0.26.3,
mkdocstrings 1.0.6, and the mkdocstrings Python handler 2.0.5. The manifest is
the source of truth for these values. Repositories with a tracked docs lock run
their build with --locked; HSSM and LANfactory instead declare every direct
docs dependency at the exact manifest version without tracking a lock; and
HSSMSpine records the exact set in requirements-docs.txt. These are three
supported reproducibility modes, not a requirement that every site commit a
lockfile.
Repository build interface¶
Each adopted repository exposes the same two-command maintainer interface:
build installs or selects the repository's pinned docs environment, performs
a strict build, and writes the rendered site to site/. serve uses the same
environment and starts the local MkDocs preview. Repositories own the
implementation because their generated reference, notebook, and system
dependency needs differ. The shared workflow deliberately accepts no install
or command input and always invokes build.
Linux system dependencies are selected with one closed
system_profile: none, blas-lapack, or gsl. The reusable workflow
rejects every other value before installation.
Build profiles¶
The shared interface has three repository-owned operating models:
- A
librarybuild installs the project together with its exact documentation dependencies so generated API reference imports the package it documents. HSSM also runs its committed-output weight guard before the strict build. - An
operationalbuild creates a docs-only environment and uses--no-install-project. It must not pull CUDA, Cognee, or other runtime stacks, and it must not need credentials, external services, or a running cluster to build or preview the site. - An
orchestrationbuild uses HSSMSpine's isolated, exactrequirements-docs.txt; it does not install ecosystem packages merely to render coordination guidance.
Notebook execution remains package-owned because each repository knows which
scientific dependencies, fixtures, and cadence make its examples trustworthy.
The reusable workflow builds the committed documentation through docs.sh; it
does not define a cross-repository notebook-execution command.
Shared build and deployment¶
HSSMSpine's .github/workflows/reusable-docs.yml is the canonical source. As
long as the Spine remains private, every external repository vendors that file
byte-for-byte at the same path and its thin caller invokes the repository-local
copy. This gives public repositories no runtime dependency on private-repository
visibility or Actions access while retaining one reviewed implementation to
synchronize.
The vendored workflow builds through the fixed script above, uploads a GitHub
Pages artifact only for a trusted main push or main manual dispatch, and
deploys that artifact with the least permissions needed. A scheduled linkcheck
never uploads or deploys. Deployments are serialized per caller repository and
an in-progress deployment is never cancelled. Rendered external-link checking
runs when the caller was started by a weekly schedule or manual dispatch.
Triggers, path filters, caller-run concurrency policy, and the
system_profile choice remain caller-owned. The reusable workflow owns only
safe deployment serialization, declares only workflow_call, does not reach
into callers with secrets, and does not accept arbitrary shell commands.
A caller grants the deployment job only the permissions it can use and calls the checked repository-local copy:
permissions:
contents: read
pages: write
id-token: write
jobs:
docs:
uses: ./.github/workflows/reusable-docs.yml
with:
system-profile: none
The caller also owns a root .lychee.toml. On weekly schedules and manual
dispatches, the reusable workflow applies it to the rendered
site/**/*.html. Before checking, it mounts site/ below the caller's
repository name so root-relative GitHub project-site URLs resolve against the
current artifact. Link checking is not part of the local docs.sh interface.
Workflow changes start in the Spine and are then copied into selected external
repositories with sync_docs_workflow.py; the local copy and caller change are
reviewed in that repository like any other CI change. An eventual migration to
lnccbrown/HSSMSpine/.github/workflows/reusable-docs.yml@<full-commit-sha> after
the Spine becomes public is explicitly deferred to a separate rollout. Until
then, callers must not mix external Spine references with the local-copy model.
Shared brand and site-owned legal text¶
The core hssm_design_system repository defines the shared visual language:
tokens, brand rules, and the MkDocs surface rules. It is a static specification
and asset repository, outside this six-site manifest. docs-brand/ implements
that specification for Material: docs-brand/tokens.json is a vendored copy of
the design tokens, and scripts/build_docs_brand.py generates
docs-brand/tokens.css from it. check_docs_contract.py fails when the
generated file is stale. See Use the design system.
The design-system theme rolls out one site at a time. Each site that has
adopted it vendors every file listed under [brand] byte-for-byte beneath its
documentation root: the generated tokens, the core stylesheet and the opt-in
notebook and landing stylesheets, the mkdocs-brand.yml INHERIT base and its
generated variants, the theme override and ecosystem partial, the navigation
mark and favicon, and self-hosted IBM Plex fonts, so it never loads Google
Fonts. An adopted site's mkdocs.yml declares
INHERIT: <docs_dir>/overrides/.mkdocs-brand.yml, or the variant named by its
manifest brand_styles (for example .mkdocs-brand-notebooks.yml for sites
that render notebooks), and does not redefine the theme name, palette, font,
logo, favicon or extra_css that the base owns. A site that has not adopted
the base yet keeps its previous assets and configuration until it migrates
(sync_docs_brand.py --repo <site> --adopt plus its config switch); both
brand checks report it as pending. Adopted docs follow the design system's
schemes: light ocean by default, navy slate for dark,
and the indigo docs-primary header in both. main.html reads
extra.release_announcement; released packages enable the release link while
non-release sites leave it disabled. The shared ecosystem link strip lives in
its own partial. Each MkDocs config mirrors brand.exclude_docs so theme Jinja
sources and the base config are consumed by MkDocs but are not copied into
rendered site/ and mistaken for reader-facing HTML by the link checker.
Each repository copies its legal_notice from the corresponding manifest
entry into MkDocs copyright. Legal text is deliberately not used as an
ecosystem navigation container: common links belong to the shared partial,
while licensing and ownership remain accurate for each repository.
Run the manifest consumers from the spine:
python scripts/sync_docs_brand.py --check
python scripts/sync_docs_workflow.py --check
python scripts/build_docs_brand.py --check
python scripts/check_docs_contract.py
python scripts/check_docs_contract.py --site-configs
python scripts/check_docs_contract.py --github-homepages
actionlint .github/workflows/*.yml
The two sync commands check live sites by default. Use --repo <name> to work
on one planned site during adoption, or --all to check every applicable site;
workflow vendoring excludes HSSMSpine itself because it is the canonical
source. The brand sync writes only to sites that have adopted the shared
INHERIT base and reports the rest as pending; a site moves over with
--repo <name> --adopt together with its config switch (see
docs-brand/README.md). --site-configs checks each checked-out site's
mkdocs.yml against the shared base: missing checkouts are skipped and
unmigrated sites are reported as pending, while a site named with --repo
must conform. The homepage command is a read-only live audit and needs authenticated
gh access to inspect private repositories. It compares GitHub metadata with
the manifest but never repairs settings. The final command is the local
equivalent of the pinned actionlint 1.7.12 check in CI.