Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maxisbey wants to merge 1 commit into
base: main
Choose a base branch
from
+27 −13
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/deploy-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@ name: Deploy Docs
on:
push:
branches:
# main is the sole deployer of the combined site (v2 at / and /v2/, v1.x
# at /v1/); the v1.x branch has no deploy workflow. A v1.x docs change is
# published by the next main deploy or a manual workflow_dispatch here.
- main
- v1.x
paths:
- docs/**
# docs pages include their code blocks from these files via `--8<--`, so a
Expand Down Expand Up @@ -48,7 +50,7 @@ jobs:
enable-cache: true
version: 0.9.5

- name: Build combined docs (v1.x at /, main at /v2/)
- name: Build combined docs (main at / and /v2/, v1.x at /v1/)
run: bash scripts/build-docs.sh site

- name: Configure Pages
Expand Down
2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
repo_name: modelcontextprotocol/python-sdk
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/

Check failure on line 7 in mkdocs.yml

View check run for this annotation

Claude / Claude Code Review

Root flip leaves docs/index.md banner linking to itself as v1.x docs 

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](https://py.sdk.modelcontextprotocol.io/)' — 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.

@claude claude Bot Jul 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 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.


# TODO(Marcelo): Add Anthropic copyright?
# copyright: © Model Context Protocol 2025 to present
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ dependencies = [

[project.urls]
Homepage = "https://modelcontextprotocol.io"
Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
Documentation = "https://py.sdk.modelcontextprotocol.io/"
Repository = "https://github.com/modelcontextprotocol/python-sdk"
Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"

Expand Down
28 changes: 20 additions & 8 deletions scripts/build-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,20 @@
#
# Build combined v1 + v2 documentation for GitHub Pages.
#
# v1 docs (from the v1.x branch) are placed at the site root.
# v2 docs (from main) are placed under /v2/.
# The current major (v2, from main) is placed at the site root and mirrored
# under /v2/; the v1 maintenance line (from the v1.x branch) is placed under
# /v1/. Per-major paths are permanent: /v2/ is a byte-identical copy of the
# root so that /v2/... links keep resolving after a future major takes the
# root, the way /v1/... does for v1 today.
#
# The two lines use different toolchains: v1.x still builds with MkDocs, while
# main builds with Zensical (which needs a pre-build step to materialise the API
# reference and a post-build step for llms.txt — see scripts/docs/). Each branch
# is fetched fresh from origin and built with its own synced `docs` group, so
# the output is identical regardless of which branch triggered the workflow.
# This script is intended to run in CI; for a local v2 preview use
# `scripts/serve-docs.sh`.
# is fetched fresh from origin and built with its own synced `docs` group. Only
# main deploys the combined site (the v1.x branch carries no deploy workflow), so
# a v1.x docs change goes live on the next main deploy or a manual
# `workflow_dispatch` of deploy-docs.yml. This script is intended to run in CI;
# for a local v2 preview use `scripts/serve-docs.sh`.
#
# Usage:
# scripts/build-docs.sh [output-dir]
Expand Down Expand Up @@ -50,6 +54,9 @@ build_site() {
fi
}

# Fetch a branch fresh from origin, build its docs, and copy the result to
# `dest`. The built tree stays in `worktree/site` afterwards so a caller can
# mirror it to a second destination.
build_branch() {
local branch="$1" worktree="$2" dest="$3"

Expand All @@ -70,7 +77,12 @@ build_branch() {

rm -rf "${OUTPUT_DIR:?}"/*

build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR"
build_branch main "$V2_WORKTREE" "$OUTPUT_DIR/v2"
# 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"

@cubic-dev-ai cubic-dev-ai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

mkdir -p "$OUTPUT_DIR/v2"
cp -a "$V2_WORKTREE/site/." "$OUTPUT_DIR/v2/"
build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR/v1"

@cubic-dev-ai cubic-dev-ai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>


echo "=== Combined docs built at $OUTPUT_DIR ==="
2 changes: 1 addition & 1 deletion src/mcp-types/pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ dependencies = [

[project.urls]
Homepage = "https://modelcontextprotocol.io"
Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
Documentation = "https://py.sdk.modelcontextprotocol.io/"
Repository = "https://github.com/modelcontextprotocol/python-sdk"
Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"

Expand Down
Loading