From 8f308a431ae666801aa3302b8e350e26504e5375 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Sat, 25 Jul 2026 23:28:43 +0000 Subject: [PATCH] Serve v2 docs at the site root, with permanent per-major paths 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. --- .github/workflows/deploy-docs.yml | 6 ++++-- mkdocs.yml | 2 +- pyproject.toml | 2 +- scripts/build-docs.sh | 28 ++++++++++++++++++++-------- src/mcp-types/pyproject.toml | 2 +- 5 files changed, 27 insertions(+), 13 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 6da800a727..334ba818c8 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -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 @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index 4c0cd06ad7..06b293f876 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_description: The official Python SDK for the Model Context Protocol 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/ # TODO(Marcelo): Add Anthropic copyright? # copyright: © Model Context Protocol 2025 to present diff --git a/pyproject.toml b/pyproject.toml index 5ce8812540..80540c29f5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 8286786091..f0991b759b 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -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] @@ -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" @@ -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" +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 ===" diff --git a/src/mcp-types/pyproject.toml b/src/mcp-types/pyproject.toml index 51cabf501b..4f3500c291 100644 --- a/src/mcp-types/pyproject.toml +++ b/src/mcp-types/pyproject.toml @@ -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"