switchyard-docs
Switchyard Docs Site
Overview
The published site is a deliberately small subset of docs/. Most files under docs/ are internal design notes; only the pages listed in mkdocs.yml's nav: (and not in exclude_docs) ship to the public site. When in doubt, prefer not to publish — add a file as internal first, then promote it once the content is stable.
Strict mode is the contract. mkdocs build --strict runs in CI (.github/workflows/docs.yml) and locally via make publish. Any warning — missing link target, unrecognized anchor, ambiguous file reference — fails the build. If you broke strict, fix the warning rather than relaxing the gate.
Repository files outside docs_dir are linked with paths relative to the Markdown source. The
mkdocs_hooks.py on_page_markdown hook rewrites valid in-repository targets to source URLs using
repo_url and extra.source_ref from mkdocs.yml before MkDocs validates links. The source ref
comes from MKDOCS_SOURCE_REF, with main as the local fallback. CI sets it to the PR head SHA or
push SHA so preview and published links resolve against the exact source commit. Missing targets and
paths that escape the repository remain relative so strict validation still exposes them.
The docs site uses the same uv toolchain as the rest of the repo. Dependencies live in the docs group in pyproject.toml; there is no separate requirements*.txt.