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/

docs/extra.css

@@ -1,26 +1,52 @@
-/* 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. */
+  /* Tighten vertical rhythm: the stock pill rows (7px 16px padding plus
+     6.3px top margins) read too airy for a deep nav; keep the pill shape
+     and active highlight, just denser. Group rows that link to an index
+     page wrap their anchor in an .md-nav__container div whose stock
+     padding is 0 — densify the inner anchor, not the wrapper. The
+     section items are excluded outright: their label is styled by the
+     section rules below, and the :not() classes here would otherwise
+     out-rank those on specificity. */
+  .md-sidebar--primary .md-nav__item:not(.md-nav__item--section) > .md-nav__link:not(.md-nav__container) {
+    padding: 4px 10px;
+    margin-top: 2px;
+  }
+  .md-sidebar--primary .md-nav__item:not(.md-nav__item--section) > .md-nav__container {
+    margin-top: 2px;
+  }
+  .md-sidebar--primary .md-nav__container > .md-nav__link {
+    padding: 4px 10px;
+  }
+  .md-sidebar--primary .md-nav__item--section {
+    margin: 1em 0;
+  }
+
+  /* Section labels: smaller, uppercase, letter-spaced, muted, and flush
+     with the guide line below them. The label is a container whose inner
+     anchor carries the stock pill padding; zero both so the label text
+     starts at the section's left edge. */
   .md-sidebar--primary .md-nav__item--section > .md-nav__link {
+    margin-top: 0;
+    margin-left: 0;
+    padding: 2px 0;
     font-size: 0.62rem;
     font-weight: 700;
     text-transform: uppercase;
     letter-spacing: 0.1em;
     color: var(--md-default-fg-color--light);
   }
+  .md-sidebar--primary .md-nav__item--section > .md-nav__link > a {
+    padding: 2px 0;
+  }
 
-  /* 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. */
+  /* Indent section children slightly and hang a guide line. */
   .md-sidebar--primary .md-nav__item--section > .md-nav {
     margin-inline-start: 0.1rem;
     border-inline-start: 0.05rem solid var(--md-default-fg-color--lightest);
@@ -32,26 +58,20 @@
     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;
   }
 
+  /* Top-level pages outside any section (the homepage entry, Protocol
+     versions, Troubleshooting, ...) share the left edge with the section
+     labels: pull the link box left by its own pill padding, so the text
+     is flush and the hover/active pill overhangs into the gutter. */
+  .md-sidebar--primary .md-nav--primary > .md-nav__list > .md-nav__item:not(.md-nav__item--section) > .md-nav__link:not(.md-nav__container) {
+    margin-inline-start: -10px;
+  }
+
   /* The sidebar repeats the site name right above the homepage nav entry;
      drop the title row on desktop (the mobile drawer still needs it for its
      drill-down back-navigation, hence the media-query scope). */
@@ -60,10 +80,18 @@
   }
 }
 
-/* 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;
+  }
+}
+
+/* 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;