Serve v2 docs at the site root, with permanent per-major paths#3176
Serve v2 docs at the site root, with permanent per-major paths#3176maxisbey wants to merge 1 commit into
Conversation
The combined GitHub Pages site now serves the current major (v2, from main) at the root and mirrors the same build under /v2/, and builds the v1 maintenance line (from v1.x) under /v1/. Per-major paths are meant to be permanent: /v2/ stays a byte-identical copy of the root so existing /v2/... links keep resolving after a future major takes the root, the way /v1/... will for v1. main becomes the sole deployer of the combined site: the deploy workflow no longer triggers on v1.x pushes, and a v1.x docs change goes live on the next main deploy or a manual workflow_dispatch. site_url and both packages' Documentation URLs point at the root as the canonical location.
📚 Documentation preview
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 5 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="scripts/build-docs.sh">
<violation number="1" location="scripts/build-docs.sh:83">
P2: The root v2 landing page will link its “v1.x documentation” callout back to itself, because the v1 site is now published at `/v1/`. Updating that absolute link to `/v1/` in the same rollout keeps the stable-version escape hatch usable as soon as this layout deploys.</violation>
<violation number="2" location="scripts/build-docs.sh:86">
P2: The first deployment after this PR will publish v1 at `/v1/` with root canonical URLs and sitemap entries, so search/social metadata points to v2 pages until the companion PR and manual rebuild occur. Publish the v1 `site_url: .../v1/` change before enabling this layout, or defer this build-path change until both branches are updated.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| build_branch main "$V2_WORKTREE" "$OUTPUT_DIR" | ||
| mkdir -p "$OUTPUT_DIR/v2" | ||
| cp -a "$V2_WORKTREE/site/." "$OUTPUT_DIR/v2/" | ||
| build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR/v1" |
There was a problem hiding this comment.
P2: The first deployment after this PR will publish v1 at /v1/ with root canonical URLs and sitemap entries, so search/social metadata points to v2 pages until the companion PR and manual rebuild occur. Publish the v1 site_url: .../v1/ change before enabling this layout, or defer this build-path change until both branches are updated.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At scripts/build-docs.sh, line 86:
<comment>The first deployment after this PR will publish v1 at `/v1/` with root canonical URLs and sitemap entries, so search/social metadata points to v2 pages until the companion PR and manual rebuild occur. Publish the v1 `site_url: .../v1/` change before enabling this layout, or defer this build-path change until both branches are updated.</comment>
<file context>
@@ -70,7 +77,12 @@ build_branch() {
+build_branch main "$V2_WORKTREE" "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR/v2"
+cp -a "$V2_WORKTREE/site/." "$OUTPUT_DIR/v2/"
+build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR/v1"
echo "=== Combined docs built at $OUTPUT_DIR ==="
</file context>
| # v2 (main) at the root, then mirrored to /v2/ from the same build, then v1 | ||
| # under /v1/. The mirror is copied from the worktree's build directory rather | ||
| # than from the root so it never picks up the /v1/ tree. | ||
| build_branch main "$V2_WORKTREE" "$OUTPUT_DIR" |
There was a problem hiding this comment.
P2: The root v2 landing page will link its “v1.x documentation” callout back to itself, because the v1 site is now published at /v1/. Updating that absolute link to /v1/ in the same rollout keeps the stable-version escape hatch usable as soon as this layout deploys.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At scripts/build-docs.sh, line 83:
<comment>The root v2 landing page will link its “v1.x documentation” callout back to itself, because the v1 site is now published at `/v1/`. Updating that absolute link to `/v1/` in the same rollout keeps the stable-version escape hatch usable as soon as this layout deploys.</comment>
<file context>
@@ -70,7 +77,12 @@ build_branch() {
+# v2 (main) at the root, then mirrored to /v2/ from the same build, then v1
+# under /v1/. The mirror is copied from the worktree's build directory rather
+# than from the root so it never picks up the /v1/ tree.
+build_branch main "$V2_WORKTREE" "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR/v2"
+cp -a "$V2_WORKTREE/site/." "$OUTPUT_DIR/v2/"
</file context>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Beyond the inline banner-link finding, I also checked the window where a push to v1.x could redeploy the old layout: the v1.x branch still carries its own deploy-docs.yml with the pre-flip script, but that can only be fixed on that branch — which is exactly what the companion [v1.x] PR in the documented merge order does, so it is a sequencing property of the release plan rather than a defect in this PR.
Extended reasoning...
The single inline finding (docs/index.md banner linking to the root as "v1.x documentation", which becomes self-referential once this PR's deploy puts v2 at the root) is confirmed by reading docs/index.md:4 against the new scripts/build-docs.sh layout. Separately, I verified on origin/v1.x that its deploy-docs.yml still triggers on v1.x pushes and its build-docs.sh still builds the old layout (v1 at root, v2 at /v2/); a v1.x push in the window between this PR and the companion [v1.x] PR would transiently revert the flip, but the fix necessarily lives on the v1.x branch and is sequenced in the PR description's merge plan, so it was correctly ruled out as a bug here. Not approving because the inline finding should be addressed in this PR, since this PR's deploy is what invalidates the link.
| repo_url: https://github.com/modelcontextprotocol/python-sdk | ||
| edit_uri: edit/main/docs/ | ||
| site_url: https://py.sdk.modelcontextprotocol.io/v2/ | ||
| site_url: https://py.sdk.modelcontextprotocol.io/ |
There was a problem hiding this comment.
🔴 This PR makes the site root serve the v2 docs, but the banner at docs/index.md:4 (untouched here) still tells readers 'For the current stable release, see the v1.x documentation' — after this PR's deploy that link circularly points back to the same v2 docs the reader is already on. Point the banner at https://py.sdk.modelcontextprotocol.io/v1/ in this PR, since the deploy triggered by this merge is what invalidates the link.
Extended reasoning...
What the bug is. The banner on the v2 docs landing page (docs/index.md:4) reads: "For the current stable release, see the v1.x documentation." Before this PR that was correct — scripts/build-docs.sh placed the v1.x build at the site root (build_branch v1.x ... $OUTPUT_DIR), so the root URL genuinely served the v1 docs. This PR swaps the layout: build_branch main ... $OUTPUT_DIR puts the v2 build at the root (mirrored to /v2/) and moves v1.x to /v1/. The banner link's target now serves v2, but its label and the file are untouched.\n\nThe code path that triggers it. The deploy fires immediately on merge: mkdocs.yml, scripts/build-docs.sh, and pyproject.toml are all in deploy-docs.yml's paths filter, and build_branch fetches origin/main fresh — so the first post-merge deploy ships this exact stale banner at the new root.\n\nWhy nothing else prevents it. The PR's stated invariant — "every existing /v2/... link keeps resolving" via the byte-identical mirror — deliberately protects deep links under the per-major paths. This link targets the root itself, whose meaning is precisely what the PR changes, so the mirror invariant doesn't cover it. The merge plan defers the "stable README/docs flip PR" to last in the release sequence, so the wrong link is live for every deploy in the interim window.\n\nStep-by-step proof.\n1. This PR merges to main; the push matches deploy-docs.yml's paths filter and the Deploy Docs job runs.\n2. scripts/build-docs.sh builds origin/main (which now contains this PR and the unchanged docs/index.md) into the site root.\n3. The published page at https://py.sdk.modelcontextprotocol.io/ renders the banner: "For the current stable release, see the v1.x documentation" → linking to https://py.sdk.modelcontextprotocol.io/.\n4. A reader on that page — say a v1 user checking whether their stable docs moved — clicks the link and lands on the exact page they were already reading, mislabeled as the v1.x documentation. The actual v1 docs at /v1/ are unreachable from the banner.\n\nImpact. The docs front page publishes a concretely wrong, self-referential link during the release window, misdirecting the audience most likely to need it (current v1.x users looking for their stable docs) with no discoverable path to /v1/.\n\nFix. One line in this PR: change the banner link in docs/index.md to https://py.sdk.modelcontextprotocol.io/v1/ (or drop/rework the banner). It belongs here rather than in the deferred flip PR because this PR's deploy is the event that invalidates the link.\n\nAll three verifiers confirmed the mechanics independently; the only disagreement was severity (one argued nit on docs-only grounds, two argued normal because the deploy triggered by this very merge publishes the wrong link). Given the entire purpose of this PR is getting the docs URLs right for the flip, shipping a mislabeled circular link on the front page is a concrete user-visible failure the PR itself creates, so it should be fixed before merge.
1 participant
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.shbuilds main once into the root and copies the same tree to/v2/, then builds v1.x under/v1/.mkdocs.ymlsite_urland both packages'DocumentationURLs point at the root as the canonical location.v1.xfrom its push triggers: main is the sole deployer of the combined site (the v1.x branch's own deploy workflow is removed in [v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line #3177), so a v1.x docs change publishes on the next main deploy or a manualworkflow_dispatch.Merge order for release day: this PR first, then #3177 (retires v1.x's own deploy and moves its
site_urlto/v1/), then a manual Deploy Docs dispatch on main so/v1/rebuilds with its newsite_url, then #3178 (the stable README/docs flip) last before the tag.How Has This Been Tested?
Ran
scripts/build-docs.shinto a scratch directory: the root serves the v2 build and/v2/is byte-identical to it (diff -rqreports 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
Checklist
AI disclosure
AI assistance was used to implement and validate this change; I reviewed the result and take responsibility for it.
AI Disclaimer