chore: switch mkdocs theme from terminal to material for visual consistency with landing page

[n0w0f]

Context

The landing page (site/index.html) uses a glassmorphism design system with Space Grotesk + JetBrains Mono fonts, a dark slate palette (#0f172a/#1e293b), and blue accent (#2563eb). The mkdocs docs use the mkdocs-terminal theme which has a retro monospace aesthetic that doesn't visually connect with the landing page.

mkdocs-material is already a dependency in pyproject.toml and supports deep customization that can closely match the landing page.

Steps

1. Switch theme in mkdocs.yaml

Replace:

theme:
  name: terminal
  palette: dark

With:

theme:
  name: material
  palette:
    scheme: slate
    primary: custom
    accent: indigo
  font:
    text: Space Grotesk
    code: JetBrains Mono
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - content.code.copy
    - search.highlight

2. Add custom color overrides

Create docs/stylesheets/extra.css:

:root {
  --md-primary-fg-color: #2563eb;
  --md-primary-bg-color: #ffffff;
  --md-accent-fg-color: #3b82f6;
}

[data-md-color-scheme="slate"] {
  --md-default-bg-color: #0f172a;
  --md-default-fg-color: #e2e8f0;
  --md-primary-fg-color: #2563eb;
  --md-accent-fg-color: #60a5fa;
  --md-code-bg-color: #1e293b;
}

Reference it in mkdocs.yaml:

extra_css:
  - stylesheets/extra.css

3. Remove terminal-specific config

• Remove copy-code.css and copy-code.js from extra_css/extra_javascript (Material has built-in code copy via content.code.copy feature)
• Remove pymdownx.blocks.details terminal-alert class mapping — use Material's native admonition styling instead:

  # Remove this:
  - pymdownx.blocks.details:
      types:
        - name: info
          class: terminal-alert
          title: Info

• Update pymdownx.highlight — Material works well with Pygments but the catppuccin-frappe style may clash; test with Material's default or switch to monokai

4. Update Pygments style

- pymdownx.highlight:
    use_pygments: true
    pygments_style: monokai
    noclasses: true

Or remove pygments_style entirely to use Material's built-in code highlighting which respects the dark scheme.

5. Clean up unused files

• Delete docs/copy-code.css
• Delete docs/copy-code.js
• Optionally remove mkdocs-terminal from pyproject.toml dependencies

6. Test

• uv run mkdocs serve — verify all pages render correctly
• Check: nav, code blocks, admonitions, tables, search, dark palette
• Compare side-by-side with landing page for visual cohesion
• Verify CI build still works (uv run mkdocs build --site-dir _build/docs)

Notes

• The terminal theme may have terminal-specific markdown patterns in docs that need updating
• Material's admonition syntax (!!! note) differs from terminal-alert classes
• Font loading: Material loads Google Fonts by default which handles Space Grotesk + JetBrains Mono automatically