MkDocs Material Setup

A general-purpose baseline for now — the plan is to trim this down to the setup I actually use, and drop the rest.

Heads up: Material for MkDocs is moving to Zensical

Worth knowing before starting a new docs site: as of November 2025, the Material for MkDocs team put the project into maintenance mode — critical bug and security fixes only, committed for at least 12 months — because upstream MkDocs itself has been unmaintained since August 2024, and MkDocs 2.0 (released early 2026) is architecturally incompatible with Material for MkDocs. Material for MkDocs 9.7.5 now pins to mkdocs<2 as a result.

The same team’s replacement is Zensical — a ground-up rewrite (a Rust differential build engine plus Python) aimed at much faster incremental rebuilds and a less constrained plugin architecture. Usefully, it reads an existing mkdocs.yml directly (nav, theme, extra, plugins all carry over largely unchanged), so the config built up below isn’t wasted effort — it’s the same config Zensical starts from when it’s time to migrate. Plugin support isn’t 1:1 automatic, though: each MkDocs plugin needs a matching Zensical module, and that list is still growing.

Practical takeaway: everything below still applies and is worth setting up now. Treat Zensical as the thing to revisit once its plugin coverage matches what a given project needs, rather than a reason to hold off on Material for MkDocs today.

1. Install

uv add --dev mkdocs-material

This pulls in mkdocs itself as a dependency of the theme package — no separate install needed.

2. Scaffold

uv run mkdocs new .

Creates mkdocs.yml and docs/index.md in the current directory.

3. Basic mkdocs.yml

site_name: My Project
repo_url: https://github.com/me/my-project

theme:
  name: material
  palette:
    - media: '(prefers-color-scheme: light)'
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - content.code.copy

nav:
  - Home: index.md
  - Guide: guide.md

4. Useful plugins

uv add --dev "mkdocstrings[python]" mkdocs-git-revision-date-localized-plugin

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: false
  - git-revision-date-localized:
      enable_creation_date: true

5. Markdown extensions worth turning on

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true

6. Local development

7. Deployment