docs: modernize the site theme#3057
Conversation
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).
📚 Documentation preview
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
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.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-site-only theme changes (mkdocs config, CSS, SVG assets) with no impact on the published package or runtime code.
Extended reasoning...
Overview
The PR touches only the documentation site: two new static SVG assets (the MCP logo mark and a favicon), a new docs/extra.css with sidebar/heading styling scoped to Material's desktop breakpoint, theme configuration in mkdocs.yml (fonts, logo, favicon, dark-mode primary color, and additional navigation.* features), and an upper bound (<10) on mkdocs-material in the docs dependency group with a matching uv.lock specifier update. No source code, tests, or published-package dependencies are modified.
Security risks
None of substance. The SVGs are static path-only assets copied from the spec repo (no scripts or external references), the CSS contains only presentational rules, and the config change stays within Material's documented options. The one externally visible effect is that the docs site now loads Inter/JetBrains Mono from Google Fonts via Material's standard theme.font mechanism — a minor third-party-request consideration for the docs site only, which the author explicitly flags and offers to self-host if maintainers prefer.
Level of scrutiny
Low. This is a docs-presentation change with zero effect on the SDK's runtime behavior, API surface, or release artifacts. The riskiest element is the mkdocs-material<10 cap, which is confined to the docs dependency group, is justified by an inline comment (the CSS relies on Material-internal nav selectors), and can be trivially reverted. mkdocs.yml has strict: true, so a misconfigured theme option would fail the docs build in CI rather than silently degrading.
Other factors
The description is thorough about what was verified on a served build (instant navigation, pruning, dark mode, mobile drawer, search), and mkdocs build --strict is reported green. The bug hunting system found no issues, and the visual outcome itself is easiest to judge from the Cloudflare preview rather than code review. Purely aesthetic preferences (font choice, dark-header color) remain a maintainer call, but nothing here needs line-by-line human scrutiny for correctness.
2 participants
A visual pass over the docs site. No content changes and no layout restructure; the sidebar keeps its always-expanded sections, it just finally looks like a hierarchy.
Motivation and Context
The site was running essentially stock Material: placeholder logo, no favicon (both were TODOs in
mkdocs.yml), default Roboto, washed-out 300-weight headings, and sidebar section children rendered flush under their group labels, so the nav read as one flat list. This brings the site in line with the MCP brand and with what comparable Material sites (pydantic, uv, ruff) do.What changed:
docs/extra.css): Material cancels its own child indent undernavigation.sections(margin-left: -.6rem); restoring it plus a subtle guide line, small uppercase section labels, tighter spacing, and hiding the duplicated site-name row. All rules are scoped to the desktop breakpoint, so the mobile drawer keeps stock styling.currentColorSVG) and favicon, copied from the spec repo's docs assets (the same pattern csharp-sdk uses); Inter / JetBrains Mono, matching modelcontextprotocol.io and the TypeScript SDK docs; headings at 600 weight and full foreground color.navigation.prune(the collapsed 109-link API Reference subtree no longer ships in every page's HTML; nav anchors on a guide page drop from 167 to 76),navigation.instant+.progress+.prefetch,navigation.footer(prev/next links),navigation.top.primary: whitetoprimary: black. The only palette rule that colors the header keys offprimary=black, so this makes the near-black dark header deliberate; link colors are identical for both values (#5e8bde).How Has This Been Tested?
mkdocs build --strictis green. Verified on a served build in a browser: instant navigation swaps pages without full reloads, pruning drops the API subtree from guide pages, footer prev/next and the back-to-top button render, dark mode has a near-black header and readable code blocks, the mobile drawer drill-down is unchanged, search works, and code annotation markers render on the What's new page. The Cloudflare preview on this PR is the easiest place to click around.Breaking Changes
None. Fonts are now loaded from Google Fonts (Material's standard
theme.fontmechanism); happy to switch tofont: falseor self-hosting if that's a concern.Types of changes
Checklist
Additional context
theme.custom_dir: docs/.overridesis new and required fortheme.icon.logo; it also makes the pre-existingcustom_icons: docs/.overrides/.iconsemoji option point at a directory that actually exists. Deliberately not enabled:navigation.expand(would open all 109 API links),toc.integrate(documented conflict withnavigation.indexes),navigation.tabs(a bigger layout change than this PR wants to be).AI Disclaimer