What is Material for MkDocs?

Material for MkDocs is a theme and feature framework on top of [MkDocs]({{ }}). Built by Martin Donath (squidfunk), it adds Material Design styling, client-side search, dark mode, code annotations, social cards, and roughly a hundred configurable features that the base MkDocs themes lack. It is the documentation framework behind FastAPI, Typer, SQLModel, Hummingbot, and many other Python projects.

Is Material for MkDocs free?

The main package (`mkdocs-material` on PyPI) is free and licensed MIT. The maintainer also runs an Insiders sponsorware program that releases newer features early to GitHub Sponsors; those features eventually merge into the public release. Most projects use the public release; Insiders is opt-in.

What is the difference between MkDocs and Material for MkDocs?

[MkDocs]({{ }}) is the static site generator. Material for MkDocs is one of its themes, but a heavyweight one: it ships its own configuration plugins, custom Markdown extensions, and feature flags. A project picks MkDocs first and then chooses Material as its theme. The choice between Material and the built-in `mkdocs`/`readthedocs` themes is comparable to the choice between [Furo]({{ }}) and Sphinx's default `alabaster`.

Is Material for MkDocs being deprecated?

Material for MkDocs entered maintenance mode in early 2026. The maintainer has announced that critical bug and security fixes will continue for at least 12 months, but new features have shifted to a successor project called [Zensical](https://zensical.org/). Zensical is built by the same team and is designed to read existing `mkdocs.yml` configurations. Greenfield projects should still feel safe choosing Material today; expect Zensical to become the migration target through 2026.

Material for MkDocs: Documentation Theme and Framework

by Tim Hopper

Documentation

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 9.7.6 (March 2026) is the current stable release, licensed MIT. Install with uv add --group docs mkdocs-material or pip install mkdocs-material.

Important

Material for MkDocs entered maintenance mode in early 2026. Critical bug and security fixes continue, but new feature work has moved to Zensical, a successor project from the same team that is designed to read existing mkdocs.yml configurations.

When to use Material for MkDocs

Pick Material for any 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 greenfield projects in 2026 and later, also evaluate Zensical, the proposed successor.

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

FastAPI, the async web framework
Typer, the CLI framework
SQLModel, the SQL ORM
Hummingbot, the algorithmic-trading framework
Pydantic, the data-validation library

Zensical and the 2026 roadmap

In early 2026, squidfunk announced that Material for MkDocs has entered maintenance mode and that future feature work will happen in Zensical, a successor static site generator from the same team. Key facts:

Critical bug and security fixes for Material continue for at least 12 months from the maintenance-mode announcement
Zensical reads existing mkdocs.yml configurations and most Material features map across
MkDocs 2.0, a separate ground-up rewrite of upstream MkDocs, is also in development; the squidfunk blog post discusses how Zensical and MkDocs 2.0 relate

For projects picking a documentation stack today, Material is still a safe choice. For projects evaluating MkDocs vs Sphinx specifically because of long-term ecosystem trends, the Zensical transition is a real factor in the decision.

Pros

The largest feature set of any MkDocs theme
Default look is usable without custom CSS
Active development and a large user base
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
Insiders sponsorware model means the newest features are gated until release
Maintenance-mode status (early 2026) introduces a question about long-term direction
Heavier than the built-in MkDocs themes; first-time setup involves more YAML

Learn More

Last updated on April 29, 2026

IPython MkDocs

Please submit corrections and feedback...