switchyard-docs

name	switchyard-docs
description	Edit or debug the published Switchyard MkDocs site. Use for docs pages, mkdocs.yml navigation, mkdocs_hooks.py source links, strict build failures, local previews, or .github/workflows/docs.yml.

Switchyard Documentation

The published site is the subset of docs/ selected by mkdocs.yml. Strict MkDocs warnings fail CI, so fix warnings rather than weakening validation.

Source Of Truth

Concern	File
Navigation, exclusions, theme	mkdocs.yml
Source-link rewriting	mkdocs_hooks.py
Local commands	docs/Makefile
Build, preview, deployment	.github/workflows/docs.yml
Documentation dependencies	pyproject.toml docs group

Workflow

1. Decide whether a new page is public. Public pages go in nav; internal notes go in exclude_docs.
2. Match the surrounding file naming and documentation style.
3. Use relative links. For repository files outside docs/, use paths relative to the Markdown file and let mkdocs_hooks.py produce the source URL.
4. Verify public examples use supported public imports and current CLI syntax.
5. Run the strict build:

cd docs
make publish

CI Constraints

• Keep the docs workflow path-filtered.