---
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.
title: switchyard-docs
canonical_url: https://skilld.dev/gh/nvidia-nemo/switchyard/switchyard-docs
last_updated: 2026-09-22T04:02:25.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install nvidia-nemo/switchyard/switchyard-docs`. Install writes the Skill files into the project, so every session loads them.

# 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:

```bash
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.