VyOS Documentation

Source for the VyOS user documentation hosted on Read the Docs at
https://docs.vyos.io.

The earlier wiki for VyOS 1.1.x and pre-1.2.0 docs is preserved on the
Wayback Machine.

Source format

Pages are MyST Markdown (.md) and
are built with Sphinx — source_suffix in docs/conf.py lists .md only.
The pre-migration RST originals are archived under docs/_rst_legacy/
for reference; they are excluded from the build and should not be edited.

VyOS-specific command directives (cfgcmd, opcmd, cmdincludemd) are
written as MyST fenced blocks and rendered as directives via
myst_fence_as_directive. Shared snippets under docs/_include/*.txt are
still RST — they are included into MyST pages through cmdincludemd, which
parses their content as RST so the legacy templates keep working unchanged.

Branches

The documentation repository tracks the same branch convention as the VyOS
source itself — one long-lived branch per release line, named after a
constellation:

Branch	VyOS version	Role
rolling	1.5+ rolling	Default branch — new contributions land here.
circinus	1.5.x	LTS docs.
sagitta	1.4.x	Previous LTS docs.
equuleus	1.3.x	Legacy.
crux	1.2.x	Legacy.

New work lands on rolling first; backports to circinus and sagitta are
requested per-PR via Mergify. See AGENTS.md for the full
contributor guide.

Build

The recommended build path is the bundled Docker image — it pins Sphinx and
the MyST/RTD plugin set to the same versions Read the Docs uses, so local
builds match production.

bashCopy
docker build -t vyos/vyos-documentation docker

# One-shot HTML build
docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
  vyos/vyos-documentation make html

# Live-reload server on port 8000
docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs \
  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
  vyos/vyos-documentation make livehtml

For a Python-only build (no Docker), use a virtualenv with the pinned
versions in requirements.txt:

bashCopy
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd docs && make html

Output lands in docs/_build/html/.

Contributing

See AGENTS.md for the full contributor guide — MyST source
conventions, the VyOS command directives (cfgcmd / opcmd /
cmdincludemd), IP-address rules, the linter and its suppression markers,
and the Copilot/CodeRabbit bot review workflow.