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,16 @@ 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.
+  # `scripts/docs/build.sh` is the whole gauntlet: build_config.py fails on
+  # nav entries without a page and pages without a nav entry, `zensical build
+  # --strict` fails on broken .md links, `pymdownx.snippets: check_paths:
+  # true` fails on a deleted `docs_src/` include, and the post-build steps
+  # fail on unresolved cross-references, inventory download failures, and
+  # broken non-markdown link targets.
+  # 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 +173,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/

docs/extra.css

@@ -1,12 +1,42 @@
-/* Sidebar hierarchy + density for MkDocs Material 9.7.x.
-   All rules scoped to the desktop sidebar breakpoint (>= 76.25em), matching
-   Material's own scoping for navigation.sections, so the mobile drill-down
-   drawer keeps stock styling. Colors use Material tokens, so the light and
-   slate schemes both work without extra palette handling. */
+/* Sidebar hierarchy + density for Zensical's UI (Material-compatible md-*
+   DOM, but different stock spacing: nav links are 8px-radius pills with
+   7px 16px padding). All rules scoped to the desktop sidebar breakpoint
+   (>= 76.25em) so the mobile drill-down drawer keeps stock styling. Colors
+   use the md-* tokens, so the light and slate schemes both work without
+   extra palette handling. */
 
 @media screen and (min-width: 76.25em) {
-  /* Section labels: smaller, uppercase, letter-spaced, muted. Covers both the
-     clickable index-page headers and the bare API Reference label. */
+  /* The sidebar is one coordinate system derived from the pill inset:
+     every row — page links, group rows, section labels — is a direct
+     .md-nav__link child of its item with the same 10px horizontal padding,
+     so all text shares one column, and hover/active pills always paint
+     10px of breathing room inside the scroll container (never clipped).
+     The padding lives on the elements Zensical paints hover/active pills
+     on (.md-nav__link[href] anchors and [for] labels — leaf links, bare
+     section labels, and the inner anchor of an .md-nav__container
+     wrapper); wrappers stay geometry-neutral, as stock. The 10px inset
+     also stays >= the 0.4rem pill radius, so the corner curve never
+     crowds the text. Vertical rhythm has a single knob: the nav list's
+     flex gap (stock 0.2rem reads airy; 2px matches the density the site
+     shipped with on Material, ~30px row pitch). */
+  .md-sidebar--primary .md-nav__list {
+    gap: 2px;
+  }
+  .md-sidebar--primary .md-nav__item > .md-nav__link:not(.md-nav__container),
+  .md-sidebar--primary .md-nav__container > .md-nav__link {
+    padding: 3px 10px;
+    margin: 0;
+  }
+  .md-sidebar--primary .md-nav__item > .md-nav__container {
+    padding: 0;
+    margin: 0;
+  }
+
+  /* Section labels: typography only — geometry comes from the row rule
+     above, so no specificity coordination is needed. */
+  .md-sidebar--primary .md-nav__item--section {
+    margin: 0.8em 0;
+  }
   .md-sidebar--primary .md-nav__item--section > .md-nav__link {
     font-size: 0.62rem;
     font-weight: 700;
@@ -15,39 +45,19 @@
     color: var(--md-default-fg-color--light);
   }
 
-  /* Indent section children and hang a guide line. Material outdents section
-     children with [dir=ltr] ... margin-left: -0.6rem, which is why they sit
-     flush under the header; restoring the margin re-exposes the stock 0.6rem
-     list padding. The logical property ties Material's physical one at
-     (0,3,0) specificity and wins on source order (extra_css loads last),
-     while staying direction-agnostic. */
+  /* Guide lines: 12px from the item box = 2px right of the label text
+     (which sits at box + 10px pill inset); children indent past them. */
   .md-sidebar--primary .md-nav__item--section > .md-nav {
-    margin-inline-start: 0.1rem;
+    margin-inline-start: 12px;
     border-inline-start: 0.05rem solid var(--md-default-fg-color--lightest);
   }
-
-  /* Same guide line for collapsible groups inside the API Reference subtree
-     (section items also carry --nested, so exclude them). */
   .md-sidebar--primary .md-nav__item--nested:not(.md-nav__item--section) > .md-nav {
+    margin-inline-start: 12px;
     border-inline-start: 0.05rem solid var(--md-default-fg-color--lightest);
   }
 
-  /* Tighten vertical rhythm (stock: 0.625em link margins, 1.25em sections).
-     The child combinator keeps this off anchors inside md-nav__container,
-     which carry their own margin-top: 0 stock rule. */
-  .md-sidebar--primary .md-nav__item > .md-nav__link {
-    margin-top: 0.45em;
-  }
-  .md-sidebar--primary .md-nav__item--section {
-    margin: 1em 0;
-  }
-  .md-sidebar--primary .md-nav__item--section > .md-nav__link {
-    margin-top: 0;
-  }
-
-  /* The current page stands out from its siblings. 700 because Material only
-     loads Inter at 300/400/700; a 600 would silently substitute the 700 face
-     anyway, but render lighter on the system-font fallback stack. */
+  /* The current page stands out from its siblings (on top of the stock
+     pill highlight). 700 because only Inter 300/400/700 are loaded. */
   .md-sidebar--primary .md-nav__link--active {
     font-weight: 700;
   }
@@ -60,10 +70,33 @@
   }
 }
 
-/* Headings: Material's 300-weight light-gray defaults read washed out; use
-   the full foreground color and a solid weight instead. 700, not 600: the
-   Google Fonts request only carries Inter 300/400/700 (see the nav__link
-   note above). */
+/* Dark scheme: Zensical's slate canvas is near-black (hsla(225,15%,5%)),
+   harsher than the Material slate this site shipped with; restore that
+   blue-grey. Code blocks and other surfaces keep Zensical's own tokens. */
+@media screen {
+  [data-md-color-scheme="slate"] {
+    --md-default-bg-color: #1e2129;
+  }
+}
+
+/* Inline code inside admonitions: the chip token is an absolute dark
+   surface designed for the page canvas, so on a tinted admonition panel it
+   sits as an opaque slab (Zensical's own docs share this bug). Re-tint it
+   tone-on-tone instead — translucent foreground, composited over whatever
+   the panel color is — the same pattern Starlight and Docusaurus ship for
+   code inside callouts. Prose chips keep the block-matching dark surface;
+   block code inside admonitions keeps its own surface too. The first
+   declaration is the fallback where color-mix is unsupported. */
+.md-typeset .admonition :not(pre) > code,
+.md-typeset details :not(pre) > code {
+  background-color: var(--md-default-fg-color--lightest);
+  background-color: color-mix(in srgb, currentcolor 11%, transparent);
+  color: inherit;
+}
+
+/* Headings: the 300-weight light-gray defaults read washed out; use the
+   full foreground color and a solid weight instead. 700, not 600: only
+   Inter 300/400/700 are loaded (see the nav__link note above). */
 .md-typeset h1,
 .md-typeset h2 {
   font-weight: 700;