Material for MkDocs

9.7.6 · maintenance · verified Sun Apr 05

Material for MkDocs is a highly customizable and responsive theme for MkDocs, a static site generator for project documentation. It transforms plain Markdown files into a professional-looking website with features like search, navigation, and extensive customization options. As of November 2025, the project is in maintenance mode (version 9.7.0 being the last feature release), with critical bug fixes and security updates guaranteed until at least November 2026, as the development team shifts focus to a new project called Zensical.

Warnings

deprecated Material for MkDocs is in maintenance mode. No new features will be added, and critical bug/security fixes are planned only until at least November 2026. Users should consider migration paths or be aware of the limited support window. The team is focusing on a new project, Zensical.
Fix: Plan for migration to alternatives (like Zensical) or ensure current features meet long-term needs within the support window.
breaking Material for MkDocs is incompatible with MkDocs 2.0. MkDocs 2.0 introduces backward-incompatible changes, including the removal/redesign of the plugin and theming systems. Users must pin their `mkdocs` dependency to `<2` to avoid breakage.
Fix: Ensure `mkdocs` is explicitly pinned to a version less than 2 (e.g., `pip install mkdocs<2`).
deprecated The `projects` and `typeset` plugins were deprecated in version 9.7.0. They are included for compatibility but are considered architectural dead ends and are provided without ongoing support.
Fix: Avoid using the `projects` and `typeset` plugins in new projects. For existing projects, be aware they will not receive updates or fixes.
breaking Upgrading from 8.x to 9.x requires configuration changes for several features that became opt-in. This includes `content.code.copy`, `content.action.*`, and `navigation.footer`. Language codes like `kr` and `no` were also renamed to `ko` and `nb` respectively.
Fix: Review the 'How to upgrade' guide in the official documentation and explicitly enable features that were previously implicit in your `mkdocs.yml` configuration. Update language codes if used.
gotcha Material for MkDocs requires Python >=3.8. Using older Python versions can lead to dependency conflicts, such as `urllib3 v2.0` requiring OpenSSL 1.1.1+, which might not be met by older Python distributions.
Fix: Ensure your Python environment is running version 3.8 or newer.

Install

pip install mkdocs-material Install latest version

Quickstart

Create a new MkDocs project, navigate into it, configure `mkdocs.yml` to use the Material theme, and then serve the documentation locally.

mkdocs new my-project
cd my-project
# Edit mkdocs.yml to apply the theme
with open('mkdocs.yml', 'w') as f:
    f.write('site_name: My Documentation\n')
    f.write('theme:\n')
    f.write('  name: material\n')
mkdocs serve

view raw JSON →