/switchyard-docs

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

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.
• Keep default permissions read-only and grant write access only to deployment jobs.
• Keep PR previews limited to same-repository pull requests.
• Do not use pull_request_target to run untrusted documentation code with write permissions.
• Build once and pass the site/ artifact to preview and deployment jobs.
• Preserve keep_files: true so a main deployment does not remove PR previews.

Common strict-build fixes are direct: add or remove a missing nav entry, repair the relative link, or explicitly exclude an internal page. Do not disable strict mode.