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:
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.highlightThe 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
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