SKILL.md
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
- Decide whether a new page is public. Public pages go in
nav; internal notes go in
exclude_docs.
- Match the surrounding file naming and documentation style.
- Use relative links. For repository files outside
docs/, use paths relative to the Markdown
file and let mkdocs_hooks.py produce the source URL.
- Verify public examples use supported public imports and current CLI syntax.
- Run the strict build:
cd docs
make publishCI 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
pullrequesttargetto run untrusted documentation code with write permissions. - Build once and pass the
site/artifact to preview and deployment jobs. - Preserve
keep_files: trueso 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.