The VyOS documentation site has carried us a long way. Sphinx + reStructuredText served the project well for years — but the world around our documentation has changed faster than our toolchain. Contributors write in Markdown. LLM coding assistants pull docs into their context windows. Reviewers expect machine-assisted feedback. AI agents need a stable, machine-readable surface to reason about VyOS configuration.
Over the past few weeks, we landed three shifts that, together, modernize docs.vyos.io across all three lifecycles, rolling, 1.5 (circinus), and 1.4 (sagitta):
Here is what changed, what it means for contributors, and why it matters for users.
Until recently, every documentation page on docs.vyos.io was authored in reStructuredText. RST is powerful, but it is also the single biggest source of friction we hear from would-be contributors: unfamiliar syntax, directive-heavy markup, and tooling that lags behind the wider Markdown ecosystem.
We converted the corpus in three discrete phases, one per release train: circinus (1.5), sagitta (1.4), and the rolling-branch flip that made MyST the primary format with no md- prefix anywhere. Rare RST overrides now live as opt-in rst-<page>.rst files for pages that genuinely need RST-only features.
The mechanics matter:
The build still runs on Sphinx; we did not swap the toolchain. We added the MyST parser on top of it, so every existing extension, theme customization, and cross-reference keeps working.
Each branch was migrated against a Playwright visual-diff harness, every page rendered before and after, pixel-compared, and regressions caught before the PR was opened.
The source_suffix is now ['.md'] only. There is no dual-source ambiguity for new contributors.
What this means for contributors: If you have ever written a GitHub README, you can now contribute to VyOS documentation. Code fences, tables, links, headings, all the syntax you already know works out of the box. The barrier to a doc PR just dropped to zero.
What this means for users: Pages render the same. Search works the same. The URLs you have bookmarked still resolve. The change is invisible by design.
Documentation review is one of the highest-leverage and most time-consuming jobs on the project. A good reviewer catches a typo, but a great reviewer catches a subtly wrong CLI example, a config snippet that drifted out of sync with the implementation, or a sentence that will be misread in three languages.
We added an automated reviewer that runs on every PR against the documentation repo. It uses the most capable Claude model tier (Opus) and is wired into GitHub Actions as the ai-validation workflow. On every PR push, it:
Checks out the PR's merge commit (the actual code that would land, not just the branch tip),
Runs a curated review prompt against the diff,
Post findings as PR comments,
Skips PRs with no Markdown changes, so infra-only churn does not burn cycles.
The workflow has been hardened over several iterations. We fixed permission scopes, NUL-byte handling in PR diffs, and edge cases around fork PRs (pull/<n>/head fetch behavior). Every doc PR across rolling, circinus, and sagitta now sees the same review treatment.
This is not a replacement for human review; it is a floor. A first pass that catches the obvious issues before a maintainer ever looks at the PR. The result is faster turnaround for contributors and more reviewer attention on the things that genuinely need a human.
If you have used Claude, Cursor, or any MCP-aware coding assistant on a VyOS configuration question, you have probably noticed the same thing we did: the model's training data is months or years out of date. It will confidently describe a CLI option that was renamed, a feature that has been moved, or a syntax that was deprecated.
Context7 is an MCP server that gives coding assistants on-demand access to the current, indexed version of a project's documentation. We registered vyos/vyos-documentation with Context7 and added a GitHub Actions workflow (Update version tags) that automatically refreshes the index whenever docs change on a release branch. The pipeline:
docs/** and context7.json (infra-only pushes are skipped),/api/v1/refresh endpoint with the correct branch/tag variant,What this means for users: When you ask an MCP-aware assistant a VyOS question, the answer is grounded in our actual current documentation, not in whatever the model happened to see during training. A query about the rolling branch returns rolling docs. A query about 1.5 returns Circinus docs. No more confident hallucinations about CLI flags that don't exist.
This is also the first dependency-free way for downstream tools, agents, and integrations to consume VyOS documentation as a current data source.
Context7 isn't the only path. Because every page is now MyST/Markdown, the raw .md sources are shipped alongside the rendered HTML, and an LLM (or any tool) can fetch a page directly from docs.vyos.io and consume it without scraping HTML. We also publish an llms.txt index and a full-content llms-full.txt bundle at the site root, generated at build time for every release train. Pick whichever surface fits your tooling: MCP via Context7, direct .md fetch, or the bundled llms.txt manifest.
Each of these three changes is useful on its own. Together, they shift the documentation site from a static publication into a living, machine-consumable knowledge base.
VyOS has always been a project where contributors and operators meet in the documentation. Now the documentation also meets the needs of the assistants that operators increasingly rely on.
The migration is done. The review automation is live. Context7 is refreshed on every merge. The next contribution you make to the VyOS docs already runs through all three.
Additional Links: