René's URL Explorer Experiment

Title: docs: replace MkDocs with Zensical by Kludex · Pull Request #3073 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: docs: replace MkDocs with Zensical by Kludex · Pull Request #3073 · modelcontextprotocol/python-sdk

X Title: docs: replace MkDocs with Zensical by Kludex · Pull Request #3073 · modelcontextprotocol/python-sdk

Description: Migrates the v2 docs build from MkDocs Material to Zensical, the Material team's successor — the same move Starlette and uvicorn made. Original migration by @Kludex; taken over to fold in review findings and empirical validation. Why this isn't a drop-in swap Zensical natively re-implements search, mkdocstrings and glightbox, but runs no arbitrary MkDocs plugins or hooks and its module/extension API hasn't shipped. This repo's docs relied on three plugin/hook-based pieces, which become standalone build steps around zensical build (the sidecar pattern): Feature this repo uses Zensical 0.0.48 Now handled by mkdocstrings, search, glightbox, emoji ✅ native mkdocs.yml (unchanged semantics) mkdocs-gen-files (the api/ tree) ❌ scripts/docs/gen_ref_pages.py mkdocs-literate-nav (the api/ nav) ❌ scripts/docs/build_config.py → mkdocs.gen.yml hooks: (llms_txt.py) ❌ no hook runtime scripts/docs/llms_txt.py (post-build) social cards ❌ (and gated on an env var no workflow ever set) dropped scripts/docs/build.sh is the single owner of the whole recipe (dependency sync → generate config/API stubs → zensical build --strict → llms.txt): shared.yml, docs-preview.yml (via the toolchain detection merged in #3081) and scripts/build-docs.sh all call it. mkdocs.yml stays the source config; mkdocs.gen.yml and docs/api/ are gitignored build artifacts. Guarantees that did not survive the toolchain swap — and where they moved Zensical builds some failure classes green that MkDocs strict-mode failed, so the sidecar scripts own them now (each verified by inducing the failure and observing the loud error): Missing nav target → ships as a broken nav link with zero diagnostics, even under --strict → build_config.py validates every nav entry against docs/ (external URLs exempt). Unresolved [name][identifier] cross-reference → renders as literal bracket text, build stays green → build.sh greps the built site for the rendered signature and fails. Missing non-markdown link target (images etc.) → Zensical's link validation only covers .md targets → llms_txt.py validates relative asset links while walking the prose. Package added without llms.txt coverage → llms_txt.py fails if a generated package index is missing from its Optional section. Config-level strict: true is parsed but not honored by Zensical (verified: only the CLI flag aborts), so the --strict flag in build.sh is the enforcement point; the old validation: block is a severity filter that at best restates defaults, at worst masks issues, and stays removed. Broken-anchor detection is on by default in Zensical and verified working. The API package index is now deliberate instead of accidental mkdocstrings renders a member re-exported across a package boundary (mcp/__init__ re-exporting mcp_types) as a full duplicate of its canonical docs when the target package happens to be loaded, and silently omits it when it isn't — so api/mcp/ had 123 headings under MkDocs (the ~50 mcp_types re-exports were just absent) and 255 under Zensical (all duplicated), from the same stub, purely by rendering order. gen_ref_pages.py pins the semantics: the mcp index renders each export as a compact one-line entry linking to its canonical page, inlining full docs only for exports documented nowhere else. This also surfaced ClientResult, which was invisible on both old sites despite being in __all__. The declarative alternative (mkdocstrings' summary option) was tested in four variants and can't do this: it produces either an empty page or full duplicate bodies with same-page anchors, drops ClientResult in every variant, and inherits the same load-order accident. preload_modules is emitted for the cross-package targets so warm incremental rebuilds can't hit AliasResolutionError (reproduced, fixed, re-verified). Visual parity and design Zensical's modern UI keeps Material's md-* DOM but ships different stock styling, so docs/extra.css was rebuilt against it (validated by measurement on the live preview, light and dark): Dark canvas back to the Material slate blue-grey this site shipped with (Zensical's near-black stays on code blocks, which keep their new styling). The sidebar is one coordinate system derived from the pill inset: labels, top-level pages, and nested rows share a single text column, guide lines thread the hierarchy, and row pitch matches the old site (~30px). Zensical's pill hover/highlight is kept. Generated API stubs carry explicit titles (Zensical's navigation.prune labels collapsed rows with the page title, which fell back to "Index"; browser tabs too). Inline code inside admonitions composites tone-on-tone over the tint (the same scoped treatment Starlight and Docusaurus ship) instead of sitting as an opaque slab — a defect Zensical's own docs currently exhibit; prose chips keep the block-matching dark surface. Verification All exercised on real builds in a clean environment (plus the docs CI job on this branch): bash scripts/docs/build.sh: strict build green with zensical 0.0.48; ~35s cold, ~3s warm incremental (a capability MkDocs didn't have). MkDocs baseline was ~33s. llms.txt, llms-full.txt, and all 50 per-page markdown renditions are byte-identical to the MkDocs pipeline's output on the same prose. Emoji, the custom mcp logo icon, palette toggles, --8<-- snippet includes, tabs and admonitions render correctly; search index at site/search.json. All six new guards were tripped on purpose and failed with their designed messages; the generator output is byte-deterministic across runs. mkdocstrings floors: 1.0.4 / mkdocstrings-python 2.0.5 (the 0.30 line crashes under Zensical with an unregistered-autorefs KeyError). griffelib is griffe's successor distribution by the same author — not a typo — and is imported directly by the generator. Breaking changes None for SDK users. For docs contributors: mkdocs serve becomes scripts/serve-docs.sh; local one-shot builds are bash scripts/docs/build.sh. Follow-up (out of scope) A [v1.x] backport of the toolchain-detecting scripts/build-docs.sh, so a v1.x-triggered Pages deploy can still build main's half of the combined site. Until it lands, deploys triggered from v1.x pushes fail (main-triggered deploys, previews and CI are unaffected). Upstream reports worth filing against Zensical: missing-nav-target detection, and unresolved autorefs rendering as literal text under --strict. AI Disclaimer

Open Graph Description: Migrates the v2 docs build from MkDocs Material to Zensical, the Material team's successor — the same move Starlette and uvicorn made. Original migration by @Kludex; taken over to fold in revie...

X Description: Migrates the v2 docs build from MkDocs Material to Zensical, the Material team&#39;s successor — the same move Starlette and uvicorn made. Original migration by @Kludex; taken over to fold in r...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3073

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width