From 5733216a5aceef8f353b4b73a4bde1ff8b494291 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Thu, 2 Jul 2026 14:56:45 +0000 Subject: [PATCH 1/2] docs: modernize the site theme Sidebar: restore the child indent that navigation.sections cancels, add a guide line, uppercase muted section labels, tighter nav rhythm, and hide the duplicated site-name row. All scoped to the desktop breakpoint; the mobile drawer keeps stock styling. Brand: use the MCP mark as header logo (currentColor SVG) and favicon, copied from the spec repo's docs assets; set Inter / JetBrains Mono to match modelcontextprotocol.io and the TypeScript SDK docs; give headings a solid weight and full foreground color instead of the 300-weight light gray. Navigation: enable navigation.prune (drops the collapsed API Reference subtree from every page's HTML), navigation.instant with progress and prefetch, navigation.footer prev/next links, and navigation.top. Switch the slate palette entry to primary black so the dark-mode header is deliberately near-black (link colors are identical for black and white primaries). --- docs/.overrides/.icons/mcp.svg | 1 + docs/extra.css | 76 ++++++++++++++++++++++++++++++++++ docs/favicon.svg | 11 +++++ mkdocs.yml | 23 +++++++--- 4 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 docs/.overrides/.icons/mcp.svg create mode 100644 docs/extra.css create mode 100644 docs/favicon.svg diff --git a/docs/.overrides/.icons/mcp.svg b/docs/.overrides/.icons/mcp.svg new file mode 100644 index 000000000..d875c1844 --- /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..4a3f3a388 --- /dev/null +++ b/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; +} 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: From 3981cc3b9dd4406829a8158af7c6152d791765db Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:04:52 +0000 Subject: [PATCH 2/2] docs: fix the header logo fill and align theme font weights The logo SVG carried fill="none" only on the root element; Material's .md-logo svg { fill: currentcolor } rule overrides a root presentation attribute, so the three open stroke paths rendered as a solid filled shape. Declaring fill="none" on each path wins over the inherited CSS value. Font weights move from 600 to 700: the theme's Google Fonts request only loads Inter at 300/400/700, so 600 was already substituting the 700 face with the webfont while rendering a lighter true-600 on the system fallback stack. The ltr/rtl rule pairs collapse into margin-inline-start and border-inline-start, which tie Material's physical outdent at equal specificity and win on source order. Cap mkdocs-material below 10: extra.css deliberately overrides theme-internal nav selectors, so a major bump should revisit it. --- docs/.overrides/.icons/mcp.svg | 2 +- docs/extra.css | 40 ++++++++++++++++------------------ pyproject.toml | 4 +++- uv.lock | 2 +- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/.overrides/.icons/mcp.svg b/docs/.overrides/.icons/mcp.svg index d875c1844..67d800b07 100644 --- a/docs/.overrides/.icons/mcp.svg +++ b/docs/.overrides/.icons/mcp.svg @@ -1 +1 @@ - + diff --git a/docs/extra.css b/docs/extra.css index 4a3f3a388..8625b05d5 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -16,26 +16,20 @@ } /* 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); + 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). */ - [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); + .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). @@ -51,9 +45,11 @@ margin-top: 0; } - /* The current page stands out from its siblings. */ + /* 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: 600; + font-weight: 700; } /* The sidebar repeats the site name right above the homepage nav entry; @@ -65,12 +61,14 @@ } /* Headings: Material's 300-weight light-gray defaults read washed out; use - the full foreground color and a solid weight instead. */ + 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: 600; + font-weight: 700; color: var(--md-default-fg-color); } .md-typeset h3 { - font-weight: 600; + font-weight: 700; } 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" }, ]