Serve v2 docs at the site root, with permanent per-major paths

Merged
MA
3mo ago
+29-15

The combined docs site currently serves the v1.x docs at the root and main's v2 docs under /v2/. For the v2 stable release this flips the layout: main's build is served at the root and mirrored under /v2/, and the v1.x maintenance docs are built under /v1/. Per-major paths are meant to be permanent, so every existing /v2/... link keeps resolving, and /v1/... will likewise keep resolving after a future major takes the root.

Motivation and Context

v2 becomes the stable line, so the site root should serve the current docs. Mirroring /v2/ as a byte copy of the same build (rather than deleting or redirecting it) means nothing already published breaks: release notes, package metadata, and external links that point at /v2/... still land on real pages.

Changes:

  • scripts/build-docs.sh builds main once into the root and copies the same tree to /v2/, then builds v1.x under /v1/.
  • mkdocs.yml site_url and both packages' Documentation URLs point at the root as the canonical location.
  • The Deploy Docs workflow drops v1.x from its push triggers: main is the sole deployer of the combined site (the v1.x branch's own deploy workflow is removed in #3177), so a v1.x docs change publishes on the next main deploy or a manual workflow_dispatch.

Merge order for release day: this PR first, then #3177 (retires v1.x's own deploy and moves its site_url to /v1/), then a manual Deploy Docs dispatch on main so /v1/ rebuilds with its new site_url, then #3178 (the stable README/docs flip) last before the tag.

How Has This Been Tested?

Ran scripts/build-docs.sh into a scratch directory: the root serves the v2 build and /v2/ is byte-identical to it (diff -rq reports zero differences across 227 files), and a second run into the populated directory rebuilds cleanly. The combined layout is exercised only at deploy time (PR CI builds the v2 site alone), so the first Deploy Docs run after merge is the confirming run for /v1/; watch it to green.

Breaking Changes

None for SDK users. For docs URLs: v1 pages previously at the root move to /v1/..., so external deep links to the old v1 root paths will 404 (accepted); v2 pages gain a canonical root URL and keep working under /v2/.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

AI disclosure

AI assistance was used to implement and validate this change; I reviewed the result and take responsibility for it.

AI Disclaimer