fix: fix multidoc cross-version links and remove duplication (modelcontextprotocol#1588)

Author: felixweinberger

.github/workflows/main.yml

@@ -108,46 +108,3 @@ jobs:
             - run: pnpm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-    # Generates API documentation (V1 + V2) and deploys to GitHub Pages on any release
-    deploy-docs:
-        runs-on: ubuntu-latest
-        if: github.event_name == 'release'
-        needs: [publish]
-
-        permissions:
-            contents: read
-            pages: write
-            id-token: write
-
-        environment:
-            name: github-pages
-            url: ${{ steps.deployment.outputs.page_url }}
-
-        steps:
-            - uses: actions/checkout@v4
-
-            - name: Install pnpm
-              uses: pnpm/action-setup@v4
-              with:
-                  run_install: false
-            - uses: actions/setup-node@v4
-              with:
-                  node-version: 24
-                  cache: pnpm
-                  cache-dependency-path: pnpm-lock.yaml
-
-            - name: Generate multi-version docs
-              run: bash scripts/generate-multidoc.sh tmp/docs-combined
-
-            - name: Configure Pages
-              uses: actions/configure-pages@v5
-
-            - name: Upload Pages artifact
-              uses: actions/upload-pages-artifact@v3
-              with:
-                  path: tmp/docs-combined
-
-            - name: Deploy to GitHub Pages
-              id: deployment
-              uses: actions/deploy-pages@v4

docs/v2-banner.js

@@ -1,7 +1,7 @@
 document.addEventListener("DOMContentLoaded", function () {
     var banner = document.createElement("div");
     banner.innerHTML =
-        "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/'>V1 docs</a>.";
+        "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/typescript-sdk/'>V1 docs</a>.";
     banner.style.cssText =
         "background:#fff3cd;color:#856404;border-bottom:1px solid #ffc107;padding:8px 16px;text-align:center;font-size:14px;";
     banner.querySelector("a").style.cssText = "color:#856404;text-decoration:underline;";

scripts/generate-multidoc.sh

@@ -17,7 +17,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-OUTPUT_DIR="${1:-$REPO_ROOT/tmp/docs-combined}"
+OUTPUT_DIR="$(cd "$REPO_ROOT" && realpath -m "${1:-tmp/docs-combined}")"
 V1_WORKTREE="$REPO_ROOT/.worktrees/v1-docs"
 V2_WORKTREE="$REPO_ROOT/.worktrees/v2-docs"
 
@@ -76,7 +76,7 @@ cat > typedoc.json << 'TYPEDOC_EOF'
     "docs/faq.md"
   ],
   "navigationLinks": {
-    "V2 Docs": "/v2/"
+    "V2 Docs": "/typescript-sdk/v2/"
   },
   "headings": {
     "readme": false
@@ -109,35 +109,6 @@ cd "$V2_WORKTREE"
 pnpm install
 pnpm -r --filter='./packages/**' build
 
-# Write the V2 pre-release banner script
-cat > docs/v2-banner.js << 'BANNER_EOF'
-document.addEventListener("DOMContentLoaded", function () {
-    var banner = document.createElement("div");
-    banner.innerHTML =
-        "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/'>V1 docs</a>.";
-    banner.style.cssText =
-        "background:#fff3cd;color:#856404;border-bottom:1px solid #ffc107;padding:8px 16px;text-align:center;font-size:14px;";
-    banner.querySelector("a").style.cssText = "color:#856404;text-decoration:underline;";
-    document.body.insertBefore(banner, document.body.firstChild);
-
-
-});
-BANNER_EOF
-
-# Patch the V2 typedoc config to add navigation links, base URL, and banner
-node -e "
-import fs from 'fs';
-const cfg = fs.readFileSync('typedoc.config.mjs', 'utf8');
-const patched = cfg.replace(
-  /export default \{/,
-  \"export default {\\n    hostedBaseUrl: 'https://modelcontextprotocol.github.io/typescript-sdk/v2/',\\n    customJs: 'docs/v2-banner.js',\"
-).replace(
-  /navigation:/,
-  \"navigationLinks: {\\n        'V1 Docs': '/',\\n    },\\n    navigation:\"
-);
-fs.writeFileSync('typedoc.config.mjs', patched);
-"
-
 npx typedoc  # outputs to tmp/docs/ per typedoc.config.mjs
 
 mkdir -p "$OUTPUT_DIR/v2"

typedoc.config.mjs

@@ -33,8 +33,9 @@ export default {
     },
     highlightLanguages: [...OptionDefaults.highlightLanguages, 'powershell'],
     projectDocuments: ['docs/documents.md'],
+    hostedBaseUrl: 'https://modelcontextprotocol.github.io/typescript-sdk/v2/',
     navigationLinks: {
-        'V1 Docs': '/'
+        'V1 Docs': '/typescript-sdk/'
     },
     navigation: {
         compactFolders: true,