docs: modernize the site theme

docs/extra.css

@@ -0,0 +1,76 @@
+/* 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 margin-left: -0.6rem, which is why they sit flush under the
+     header; restoring the margin re-exposes the stock 0.6rem list padding. */
+  [dir="ltr"] .md-sidebar--primary .md-nav__item--section > .md-nav {
+    margin-left: 0.1rem;
+    border-left: 0.05rem solid var(--md-default-fg-color--lightest);
+  }
+  [dir="rtl"] .md-sidebar--primary .md-nav__item--section > .md-nav {
+    margin-right: 0.1rem;
+    border-right: 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). */
+  [dir="ltr"] .md-sidebar--primary
+    .md-nav__item--nested:not(.md-nav__item--section) > .md-nav {
+    border-left: 0.05rem solid var(--md-default-fg-color--lightest);
+  }
+  [dir="rtl"] .md-sidebar--primary
+    .md-nav__item--nested:not(.md-nav__item--section) > .md-nav {
+    border-right: 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. */
+  .md-sidebar--primary .md-nav__link--active {
+    font-weight: 600;
+  }
+
+  /* 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. */
+.md-typeset h1,
+.md-typeset h2 {
+  font-weight: 600;
+  color: var(--md-default-fg-color);
+}
+.md-typeset h3 {
+  font-weight: 600;
+}

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: