diff --git a/docs/.overrides/.icons/mcp.svg b/docs/.overrides/.icons/mcp.svg
new file mode 100644
index 000000000..67d800b07
--- /dev/null
+++ b/docs/.overrides/.icons/mcp.svg
@@ -0,0 +1 @@
+
diff --git a/docs/extra.css b/docs/extra.css
new file mode 100644
index 000000000..8625b05d5
--- /dev/null
+++ b/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;
+}
diff --git a/docs/favicon.svg b/docs/favicon.svg
new file mode 100644
index 000000000..a280d7fdb
--- /dev/null
+++ b/docs/favicon.svg
@@ -0,0 +1,11 @@
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 2d4754f1c..5f19b8982 100644
--- a/mkdocs.yml
+++ b/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:
diff --git a/pyproject.toml b/pyproject.toml
index c46f81d8d..2260ea2e2 100644
--- a/pyproject.toml
+++ b/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"]
diff --git a/uv.lock b/uv.lock
index 2646eda9d..e9abba117 100644
--- a/uv.lock
+++ b/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" },
]