Skip to content

Material for MkDocs: Documentation Theme and Framework

Material for MkDocs is a theme and feature framework for MkDocs. Built by Martin Donath (squidfunk), it layers Material Design styling, client-side search, dark mode, code annotations, and a wide configuration surface on top of the base MkDocs build pipeline.

Note

Material for MkDocs is licensed MIT. Install with uv add --group docs mkdocs-material or pip install mkdocs-material.

Important

Material for MkDocs is in maintenance mode. It receives critical bug and security fixes but no new features. Feature development continues in Zensical, a successor from the same team that reads existing mkdocs.yml configurations.

When to use Material for MkDocs

Pick Material for an existing MkDocs site that wants search, dark mode, code annotations, admonitions, and social cards without authoring custom CSS. It is the most-installed third-party MkDocs theme on PyPI and the theme behind FastAPI, Pydantic, Typer, and SQLModel. For a greenfield project, compare the current options in Which Python documentation tool should I use?.

Key Features

  • Material Design styling with light and dark variants
  • Client-side search with offline support
  • Code annotations: rich text overlays inside code blocks
  • Admonition support (notes, warnings, tips) via Python-Markdown
  • Social cards: auto-generated preview images for each page
  • Internationalization for over 60 languages
  • Customizable color palettes, fonts, icons, and emoji
  • Plugin ecosystem (tags, blog, redirects, instant navigation)

Configuration

Material is configured under the theme block in mkdocs.yml:

mkdocs.yml
site_name: mypackage
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.annotate
markdown_extensions:
  - admonition
  - pymdownx.superfences
  - pymdownx.highlight

The features list is where most Material configuration happens; each entry toggles a specific UX feature (sticky tabs, instant navigation, code copy buttons, and so on). The full list lives in the setup guide.

Projects Using Material for MkDocs

Plan a move to Zensical

Zensical consolidates static-site generation and the theme into one project. It preserves the standard MkDocs project structure and can build from an existing mkdocs.yml.

Material settings and the classic theme preserve much of an existing site’s appearance. Plugin support is narrower: Zensical replaces selected MkDocs plugins, while unsupported plugins do not run. Compare representative pages and verify every plugin before switching the production build.

Keep Material for an existing site that still works. For a new project, use the Python documentation tool comparison to choose between Zensical, Great Docs, and Sphinx.

Pros

  • The largest feature set of any MkDocs theme
  • Default look is usable without custom CSS
  • Previously sponsor-only features are available in the public package
  • Client-side search with offline support out of the box
  • Used by FastAPI, Pydantic, Typer, and SQLModel

Cons

  • Configuration surface is large; full feature audit takes time
  • Maintenance mode means no new features
  • Moving to Zensical requires checking plugins and template overrides
  • Heavier than the built-in MkDocs themes; first-time setup involves more YAML
Last updated on