docs: replace MkDocs with Zensical

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - src/mcp/**
       - src/mcp-types/**
       - scripts/build-docs.sh
+      - scripts/docs/**
       - pyproject.toml
       - uv.lock
       - .github/workflows/deploy-docs.yml
@@ -49,9 +50,6 @@ jobs:
 
       - name: Build combined docs (v1.x at /, main at /v2/)
         run: bash scripts/build-docs.sh site
-        env:
-          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
-          NO_MKDOCS_2_WARNING: "1"
 
       - name: Configure Pages
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

.github/workflows/shared.yml

@@ -139,11 +139,13 @@ jobs:
       - name: Check README snippets are up to date
         run: uv run --frozen scripts/update_readme_snippets.py --check
 
-  # `mkdocs.yml` sets `strict: true` and `pymdownx.snippets: check_paths: true`,
-  # but until this job existed the docs were only ever built post-merge by
-  # `deploy-docs.yml`, so a broken link, a missing nav target, or a deleted
-  # `docs_src/` include went green on the PR and broke the next deploy of main.
-  # This is the check path; `deploy-docs.yml` stays the deploy path.
+  # `zensical build --strict` fails on broken links / missing nav targets and
+  # `pymdownx.snippets: check_paths: true` fails on a deleted `docs_src/`
+  # include; the llms_txt step additionally re-resolves every snippet and link.
+  # Until this job existed the docs were only ever built post-merge by
+  # `deploy-docs.yml`, so those failures went green on the PR and broke the next
+  # deploy of main. This is the check path; `deploy-docs.yml` stays the deploy
+  # path.
   docs:
     runs-on: ubuntu-latest
     steps:
@@ -168,11 +170,5 @@ jobs:
           enable-cache: true
           version: 0.9.5
 
-      - name: Install dependencies
-        run: uv sync --frozen --all-extras --python 3.10
-
       - name: Build the docs in strict mode
-        run: uv run --frozen --no-sync mkdocs build --strict
-        env:
-          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
-          NO_MKDOCS_2_WARNING: "1"
+        run: bash scripts/docs/build.sh

.gitignore

@@ -141,9 +141,13 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# documentation
 /site
 /.worktrees/
+# Generated at build time by scripts/docs/ (the API reference tree and the
+# concrete Zensical config spliced from mkdocs.yml).
+/docs/api/
+/mkdocs.gen.yml
 
 # mypy
 .mypy_cache/

mkdocs.yml

@@ -1,6 +1,5 @@
 site_name: MCP Python SDK
 site_description: The official Python SDK for the Model Context Protocol
-strict: true
 
 repo_name: modelcontextprotocol/python-sdk
 repo_url: https://github.com/modelcontextprotocol/python-sdk
@@ -10,6 +9,9 @@ site_url: https://py.sdk.modelcontextprotocol.io/v2/
 # TODO(Marcelo): Add Anthropic copyright?
 # copyright: © Model Context Protocol 2025 to present
 
+# The "API Reference" entry is a placeholder: `scripts/docs/gen_ref_pages.py`
+# generates the `docs/api/` tree and `scripts/docs/build_config.py` splices the
+# real nested nav in before the build. See `scripts/docs/build.sh`.
 nav:
   - MCP Python SDK: index.md
   - "What's new in v2": whats-new.md
@@ -122,13 +124,6 @@ theme:
 extra_css:
   - extra.css
 
-# https://www.mkdocs.org/user-guide/configuration/#validation
-validation:
-  omitted_files: warn
-  absolute_links: warn
-  unrecognized_links: warn
-  anchors: warn
-
 markdown_extensions:
   - tables
   - admonition
@@ -138,29 +133,28 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.critic
   - pymdownx.mark
-  - pymdownx.superfences
   # Code examples live as complete, importable, tested files under `docs_src/`
   # and are included into pages with `--8<-- "docs_src/<chapter>/tutorialNNN.py"`
-  # (resolved against the repo root regardless of the build's working
-  # directory; the extension's default base_path is the CWD).
-  # `check_paths: true` + `strict: true` turn a renamed/deleted example into a
-  # build failure instead of a silently empty code block.
+  # (resolved against the repo root, which is the build's working directory).
+  # `check_paths: true` turns a renamed/deleted example into a build failure
+  # instead of a silently empty code block.
   - pymdownx.snippets:
-      base_path: !relative $config_dir
+      base_path: [.]
       check_paths: true
   - pymdownx.tilde
   - pymdownx.inlinehilite
   - pymdownx.highlight:
       pygments_lang_class: true
-  - pymdownx.extra:
-      pymdownx.superfences:
-        custom_fences:
-          - name: mermaid
-            class: mermaid
-            format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: pymdownx.superfences.fence_code_format
+  # Zensical re-implements the emoji extension; the generator/index functions
+  # live under `zensical.extensions.emoji`, not `material.extensions.emoji`.
   - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: zensical.extensions.emoji.twemoji
+      emoji_generator: zensical.extensions.emoji.to_svg
       options:
         custom_icons:
           - docs/.overrides/.icons
@@ -170,23 +164,22 @@ markdown_extensions:
       custom_checkbox: true
   - sane_lists # this means you can start a list from any number
 
+# Zensical natively watches these beyond docs/: page content is assembled
+# from src/ (mkdocstrings) and docs_src/ (snippet includes), so serve
+# live-reload must react to both.
 watch:
   - src
   - docs_src
 
-hooks:
-  - docs/hooks/llms_txt.py
-
+# Zensical natively re-implements `search`, `glightbox` and `mkdocstrings`; it
+# does not run arbitrary MkDocs plugins or hooks. The former `gen-files`,
+# `literate-nav` and `llms_txt` hook are handled by the standalone scripts
+# under `scripts/docs/` (see scripts/docs/build.sh). The `social` plugin was
+# dropped: Zensical has no social-card support, and the cards were gated on
+# ENABLE_SOCIAL_CARDS, which no workflow ever set.
 plugins:
   - search
-  - social:
-      enabled: !ENV [ENABLE_SOCIAL_CARDS, false]
   - glightbox
-  - gen-files:
-      scripts:
-        - docs/hooks/gen_ref_pages.py
-  - literate-nav:
-      nav_file: SUMMARY.md
   - mkdocstrings:
       handlers:
         python: