docs: modernize the site theme (#3057)

docs/.overrides/.icons/mcp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180"><path fill="none" d="M23.5996 85.2532L86.2021 22.6507C94.8457 14.0071 108.86 14.0071 117.503 22.6507C126.147 31.2942 126.147 45.3083 117.503 53.9519L70.2254 101.23" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M70.8789 100.578L117.504 53.952C126.148 45.3083 140.163 45.3083 148.806 53.952L149.132 54.278C157.776 62.9216 157.776 76.9357 149.132 85.5792L92.5139 142.198C89.6327 145.079 89.6327 149.75 92.5139 152.631L104.14 164.257" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M101.853 38.3013L55.553 84.6011C46.9094 93.2447 46.9094 107.258 55.553 115.902C64.1966 124.546 78.2106 124.546 86.8543 115.902L133.154 69.6025" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/></svg>

docs/extra.css

@@ -0,0 +1,74 @@
+/* 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. */
+
+@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. */
+  .md-sidebar--primary .md-nav__item--section > .md-nav__link {
+    font-size: 0.62rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    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. */
+  .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);
+  }
+
+  /* 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 {
+    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. */
+  .md-sidebar--primary .md-nav__link--active {
+    font-weight: 700;
+  }
+
+  /* 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). */
+  .md-sidebar--primary .md-nav--primary > .md-nav__title {
+    display: none;
+  }
+}
+
+/* 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). */
+.md-typeset h1,
+.md-typeset h2 {
+  font-weight: 700;
+  color: var(--md-default-fg-color);
+}
+.md-typeset h3 {
+  font-weight: 700;
+}

docs/favicon.svg

@@ -0,0 +1,11 @@
+<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="180" height="180" rx="24" fill="black"/>
+<mask id="mask0_246_1229" style="mask-type:luminance" maskUnits="userSpaceOnUse" x="7" y="7" width="166" height="166">
+<path d="M173 7H7V173H173V7Z" fill="white"/>
+</mask>
+<g mask="url(#mask0_246_1229)">
+<path d="M23.5996 85.2532L86.2021 22.6507C94.8457 14.0071 108.86 14.0071 117.503 22.6507C126.147 31.2942 126.147 45.3083 117.503 53.9519L70.2254 101.23" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+<path d="M70.8789 100.578L117.504 53.952C126.148 45.3083 140.163 45.3083 148.806 53.952L149.132 54.278C157.776 62.9216 157.776 76.9357 149.132 85.5792L92.5139 142.198C89.6327 145.079 89.6327 149.75 92.5139 152.631L104.14 164.257" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+<path d="M101.853 38.3013L55.553 84.6011C46.9094 93.2447 46.9094 107.258 55.553 115.902C64.1966 124.546 78.2106 124.546 86.8543 115.902L133.154 69.6025" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+</g>
+</svg>

mkdocs.yml

@@ -69,6 +69,13 @@ nav:
 
 theme:
   name: "material"
+  custom_dir: docs/.overrides
+  font:
+    text: Inter
+    code: JetBrains Mono
+  icon:
+    logo: mcp
+  favicon: favicon.svg
   palette:
     - media: "(prefers-color-scheme)"
       scheme: default
@@ -86,7 +93,7 @@ theme:
         name: "Switch to dark mode"
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
-      primary: white
+      primary: black
       accent: white
       toggle:
         icon: material/lightbulb-auto-outline
@@ -98,14 +105,20 @@ theme:
     - content.code.annotate
     - content.code.copy
     - content.code.select
-    - navigation.path
+    - navigation.footer
     - navigation.indexes
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.path
+    - navigation.prune
     - navigation.sections
+    - navigation.top
     - navigation.tracking
     - toc.follow
-  # logo: "img/logo-white.svg"
-  # TODO(Marcelo): Add a favicon.
-  # favicon: "favicon.ico"
+
+extra_css:
+  - extra.css
 
 # https://www.mkdocs.org/user-guide/configuration/#validation
 validation:

pyproject.toml

@@ -80,7 +80,9 @@ docs = [
     "mkdocs-gen-files>=0.5.0",
     "mkdocs-glightbox>=0.4.0",
     "mkdocs-literate-nav>=0.6.1",
-    "mkdocs-material[imaging]>=9.7.0",
+    # docs/extra.css overrides Material-internal nav selectors; revisit it on a
+    # major bump before raising this cap.
+    "mkdocs-material[imaging]>=9.7.0,<10",
     "mkdocstrings-python>=2.0.1",
 ]
 codegen = ["datamodel-code-generator==0.57.0"]

uv.lock

@@ -1020,7 +1020,7 @@ docs = [
     { name = "mkdocs-gen-files", specifier = ">=0.5.0" },
     { name = "mkdocs-glightbox", specifier = ">=0.4.0" },
     { name = "mkdocs-literate-nav", specifier = ">=0.6.1" },
-    { name = "mkdocs-material", extras = ["imaging"], specifier = ">=9.7.0" },
+    { name = "mkdocs-material", extras = ["imaging"], specifier = ">=9.7.0,<10" },
     { name = "mkdocstrings-python", specifier = ">=2.0.1" },
 ]