From 2e64e126c62d645c40c9012672f894b32295c21e Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Thu, 9 Jul 2026 13:48:25 +0000
Subject: [PATCH] [v1.x] ci: pick the docs toolchain per worktree in
 build-docs.sh

The combined Pages deploy builds both v1.x (site root) and main (/v2/)
from whichever branch triggered it. main now builds with Zensical
(modelcontextprotocol/python-sdk#3073), so the hardcoded mkdocs command
here breaks any v1.x-triggered deploy. Copy main's build-docs.sh verbatim:
each worktree is built with the toolchain its own files declare, mkdocs
remaining the fallback for this branch.
---
 scripts/build-docs.sh | 36 +++++++++++++++++++++++++++++-------
 1 file changed, 29 insertions(+), 7 deletions(-)

diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh
index 5a61309acf..8286786091 100755
--- a/scripts/build-docs.sh
+++ b/scripts/build-docs.sh
@@ -1,13 +1,17 @@
 #!/usr/bin/env bash
 #
-# Build combined v1 + v2 MkDocs documentation for GitHub Pages.
+# 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/.
 #
-# Both branches are fetched fresh from origin, so the output is identical
-# regardless of which branch triggered the workflow. This script is intended
-# to run in CI; for local single-branch preview use `uv run mkdocs serve`.
+# 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`.
 #
 # Usage:
 #   scripts/build-docs.sh [output-dir]
@@ -30,7 +34,21 @@ cleanup() {
 }
 trap cleanup EXIT
 
-rm -rf "${OUTPUT_DIR:?}"/*
+# Build the checked-out worktree into its local `site/`, picking the toolchain
+# from the branch's own files rather than hard-coding it here: a branch that
+# ships the Zensical build recipe (scripts/docs/build.sh) builds with it,
+# otherwise it falls back to MkDocs. This keeps the combined build correct
+# regardless of which branch triggered it. Zensical requires site_dir to live
+# within the project root, so both paths build to the local `site/` and let
+# the caller copy it to its destination.
+build_site() {
+    if [[ -f scripts/docs/build.sh ]]; then
+        bash scripts/docs/build.sh
+    else
+        uv sync --frozen --group docs
+        NO_MKDOCS_2_WARNING=1 uv run --frozen --no-sync mkdocs build --site-dir site
+    fi
+}
 
 build_branch() {
     local branch="$1" worktree="$2" dest="$3"
@@ -43,11 +61,15 @@ build_branch() {
 
     (
         cd "$worktree"
-        uv sync --frozen --group docs
-        uv run --frozen --no-sync mkdocs build --site-dir "$dest"
+        rm -rf site
+        build_site
+        mkdir -p "$dest"
+        cp -a site/. "$dest/"
     )
 }
 
+rm -rf "${OUTPUT_DIR:?}"/*
+
 build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR"
 build_branch main "$V2_WORKTREE" "$OUTPUT_DIR/v2"