docs: replace MkDocs with Zensical (#3073)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com>

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,45 +124,41 @@ 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
+  - abbr
   - admonition
   - attr_list
+  - def_list
+  - footnotes
   - md_in_html
+  - pymdownx.betterem
   - pymdownx.details
   - 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 +168,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: