docs: implement deep re-routing, pagination, and migration banner

.github/workflows/cloudflare_sync.yaml

@@ -0,0 +1,42 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "Sync v1 docsite to Cloudflare"
+
+concurrency:
+  group: cloudflare-sync
+  cancel-in-progress: true
+
+on:
+  workflow_run:
+    workflows: ["CF: Deploy Dev Docs", "CF: Deploy Versioned Docs", "CF: Deploy Previous Version Docs"]
+    types: [completed]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: 'cloudflare-pages'
+      - name: Cleanup
+        run: |
+          rm -rf .git
+      - name: Cloudflare Deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy . --project-name=toolbox-docs --branch=main

.github/workflows/deploy_dev_docs_to_cf.yaml

@@ -0,0 +1,87 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "CF: Deploy Dev Docs"
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs*_cf.yaml'
+      - '.github/workflows/deploy*_cf.yaml'
+      - '.hugo/**'
+
+  # Allow triggering manually.
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: .hugo
+    # This shared concurrency group ensures only one docs deployment runs at a time.
+    concurrency:
+      group: cf-docs-update
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
+        with:
+          hugo-version: "0.145.0"
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: "22"
+
+      - name: Cache dependencies
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - run: npm ci
+      - run: hugo --minify --config hugo.cloudflare.toml
+        env:
+          HUGO_BASEURL: https://mcp-toolbox.dev/dev/
+          HUGO_RELATIVEURLS: false
+
+      - name: Create Staging Directory
+        run: |
+          mkdir staging
+          mv public staging/dev
+          mv staging/dev/releases.releases staging/releases.releases
+
+      - name: Push to Cloudflare Branch
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./.hugo/staging
+          publish_branch: cloudflare-pages
+          keep_files: true
+          commit_message: "deploy: ${{ github.event.head_commit.message }}"

.github/workflows/deploy_previous_version_docs_to_cf.yaml

@@ -0,0 +1,104 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "CF: Deploy Previous Version Docs"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_tag:
+        description: 'The old version tag to build docs for (e.g., v0.15.0)'
+        required: true
+        type: string
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main branch (for latest templates and theme)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: 'main'
+          submodules: 'recursive'
+          fetch-depth: 0
+
+      - name: Checkout old content from tag into a temporary directory
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.inputs.version_tag }}
+          path: 'old_version_source' # Checkout into a temp subdir
+          # Sparse checkout to only get the content directory
+          sparse-checkout: |
+            docs
+
+      - name: Replace content with old version
+        run: |
+          # Remove the current content directory from the main branch checkout
+          rm -rf docs/
+          # Move the old content directory into place
+          mv ./old_version_source/docs docs
+
+      - name: Setup Hugo and Node
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
+        with:
+          hugo-version: "0.145.0"
+          extended: true
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: "22"
+
+      - name: Install Dependencies
+        run: npm ci
+        working-directory: .hugo
+
+      - name: Build Hugo Site for Archived Version
+        run: hugo --minify --config hugo.cloudflare.toml
+        working-directory: .hugo
+        env:
+          HUGO_BASEURL: https://mcp-toolbox.dev/${{ github.event.inputs.version_tag }}/
+          HUGO_RELATIVEURLS: false
+
+      - name: Deploy to cloudflare-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .hugo/public
+          publish_branch: cloudflare-pages
+          destination_dir: ./${{ github.event.inputs.version_tag }}
+          keep_files: true
+          allow_empty_commit: true
+          commit_message: "docs(backport): deploy docs for ${{ github.event.inputs.version_tag }}"
+
+      - name: Clean Build Directory
+        run: rm -rf .hugo/public
+
+      - name: Build Hugo Site
+        run: hugo --minify --config hugo.cloudflare.toml
+        working-directory: .hugo
+        env:
+          HUGO_BASEURL: https://mcp-toolbox.dev/
+          HUGO_RELATIVEURLS: false
+
+      - name: Deploy to root
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .hugo/public
+          publish_branch: cloudflare-pages
+          keep_files: true
+          allow_empty_commit: true
+          commit_message: "deploy: docs to root for ${{ github.event.inputs.version_tag }}"

.github/workflows/deploy_versioned_docs_to_cf.yaml

@@ -0,0 +1,93 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "CF: Deploy Versioned Docs"
+
+permissions:
+  contents: write
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-24.04
+    # This shared concurrency group ensures only one docs deployment runs at a time.
+    concurrency:
+      group: cf-docs-update
+      cancel-in-progress: false
+    steps:
+      - name: Checkout Code at Tag
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Get Version from Release Tag
+        id: get_version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: echo "VERSION=${RELEASE_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3
+        with:
+          hugo-version: "0.145.0"
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
+        with:
+          node-version: "22"
+
+      - name: Install Dependencies
+        run: npm ci
+        working-directory: .hugo
+
+      - name: Build Hugo Site
+        run: hugo --minify --config hugo.cloudflare.toml
+        working-directory: .hugo
+        env:
+          HUGO_BASEURL: https://mcp-toolbox.dev/${{ steps.get_version.outputs.VERSION }}/
+          HUGO_RELATIVEURLS: false
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .hugo/public
+          publish_branch: cloudflare-pages
+          destination_dir: ./${{ steps.get_version.outputs.VERSION }}
+          keep_files: true
+          commit_message: "deploy: docs for ${{ steps.get_version.outputs.VERSION }}"
+
+      - name: Clean Build Directory
+        run: rm -rf .hugo/public
+
+      - name: Build Hugo Site
+        run: hugo --minify --config hugo.cloudflare.toml
+        working-directory: .hugo
+        env:
+          HUGO_BASEURL: https://mcp-toolbox.dev/
+          HUGO_RELATIVEURLS: false
+
+      - name: Deploy to root
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .hugo/public
+          publish_branch: cloudflare-pages
+          keep_files: true
+          allow_empty_commit: true
+          commit_message: "deploy: docs to root for ${{ steps.get_version.outputs.VERSION }}"