VyOS Networks Blog

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

1. Full RST → MyST/Markdown migration of the documentation corpus.
2. Opus-tier AI review on every documentation pull request.
3. Context7 integration so MCP-aware coding assistants always pull the current version of our docs.

Here is what changed, what it means for contributors, and why it matters for users.

1. From RST to MyST — Markdown as a first-class citizen

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.

2. AI-assisted review, Opus on every documentation PR

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.

3. Context7, keeping AI assistants pinned to the current docs

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:

• Watches push to docs/** and context7.json (infra-only pushes are skipped),
• Calls Context7's /api/v1/refresh endpoint with the correct branch/tag variant,
• Guards against stale re-runs by re-checking HEAD before posting (Actions' "Re-run jobs" replays the original SHA, a HEAD-equivalence guard prevents pushing a stale snapshot to Context7),
• Runs with per-branch concurrency so parallel pushes don't trample each other.

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.

Why this matters, taken together

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.

• Contributors write in the format they already know.
• Reviewers get a quality floor before they ever see a PR.
• Users get docs that render the same as before, with stable URLs.
• AI assistants get a fresh, indexed, branch-aware source of truth.

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.

MCP-aware assistant at Context7, ask it about VyOS,

and see the difference for yourself!

Additional Links:

• VyOS User Guide

• Open a PR, your first one will be Markdown, reviewed by the AI floor, and indexed to Context7 on merge