docs: modernize the site theme

Merged
MA
4mo ago
+108-7

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:

  • Sidebar hierarchy (docs/extra.css): Material cancels its own child indent under navigation.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.
  • Brand: the MCP mark as header logo (currentColor SVG) 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 features: 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.
  • Dark mode: the slate palette entry moves from primary: white to primary: black. The only palette rule that colors the header keys off primary=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 --strict is 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.font mechanism); happy to switch to font: false or self-hosting if that's a concern.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

theme.custom_dir: docs/.overrides is new and required for theme.icon.logo; it also makes the pre-existing custom_icons: docs/.overrides/.icons emoji option point at a directory that actually exists. Deliberately not enabled: navigation.expand (would open all 109 API links), toc.integrate (documented conflict with navigation.indexes), navigation.tabs (a bigger layout change than this PR wants to be).

AI Disclaimer