Skip to content
Get packs

Guide · Open source

How to use mkdocs-material: install, configure and publish docs

Updated · written with AI from the project's own documentation and checked against our catalogue data

Material for MkDocs is a theme for MkDocs, a tool that builds static documentation websites from Markdown files. It adds a mobile-friendly design, search, and navigation on top of MkDocs. This guide shows how to install it, turn it on in your config file, and decide whether it fits your project.

Material for MkDocssquidfunk/mkdocs-material · ★ 27.6k · MIT

Quick start

  1. 1Check Python. Confirm you have Python 3.11 or newer installed.
  2. 2Install the theme. Run pip install mkdocs-material in your terminal.
  3. 3Set the theme. Add theme name material to your mkdocs.yml file.
  4. 4Write Markdown pages. Create your documentation as Markdown files in your project.
  5. 5Review the end-of-life notice. Check the README's May 5, 2027 end-of-life date and the Zensical migration guide if you need long-term support.

What you need before you install mkdocs-material

Material for MkDocs requires Python 3.11 or newer. It is installed with pip, the Python package installer.

It is a good fit if you already write documentation in Markdown or plan to use MkDocs. It is less suited to people who want a no-code website builder, because setup involves editing a YAML config file and Markdown files.

  • Python 3.11 or newer
  • Markdown files for your documentation
  • A mkdocs.yml configuration file

How do you install mkdocs-material with pip?

Run the following command in your terminal to install the theme. The README uses pip for installation.

pip install mkdocs-material

How do you enable the theme in mkdocs.yml?

Open the mkdocs.yml file in your project and add the theme setting. This tells MkDocs to use Material for MkDocs when it builds your site. For configuration options, the project points to its documentation site.

theme: name: material

What does the theme give you?

According to the project, Material for MkDocs lets you write documentation in Markdown and produce a static site that is searchable, customizable, available in more than 60 languages, and designed for all devices.

The README says the theme is used by projects including FastAPI, Pydantic, Ruff, OpenSSL, AWS Copilot, and Google Accompanist.

  • Searchable site
  • Mobile-friendly and desktop design
  • Navigation built from your Markdown pages
  • Support for more than 60 languages
  • Configurable through mkdocs.yml

Check the end-of-life notice before you start

The README states that Material for MkDocs reaches end of life on May 5, 2027, and that critical fixes and security updates continue until then. The project recommends Zensical, a maintained successor that is also MIT-licensed and can be evaluated alongside MkDocs using your existing mkdocs.yml.

If you need a tool with long-term support, review the migration guide the project links to before committing to this theme.

What people use it for

  • Publishing project documentation for an open source library
  • Building product documentation for a commercial project
  • Creating a searchable docs site that works on phones and desktops
  • Hosting documentation for Python projects that already use MkDocs

Frequently asked questions

Is mkdocs-material free?

Yes. It is released under the MIT License, which permits use, copying, modification, and distribution, including for commercial work, provided the copyright notice is included. The license text says the software is provided as is, without warranty.

What version of Python does mkdocs-material need?

The README says Material for MkDocs requires Python 3.11 or newer. Check your Python version before running the pip install command.

How do I install mkdocs-material?

Run pip install mkdocs-material in your terminal. Then add theme name material to your mkdocs.yml file so MkDocs uses the theme.

Is mkdocs-material still maintained?

The README says it reaches end of life on May 5, 2027, with critical fixes and security updates until that date. The project recommends Zensical, a maintained successor, and links a migration guide.

Is mkdocs-material a no-code website builder?

No. The README and project analysis indicate it requires editing a YAML config file and writing Markdown files. People who want a visual, no-code builder should look elsewhere.

How does mkdocs-material compare to Docusaurus, Sphinx, or Hugo?

Material for MkDocs is a theme on top of MkDocs, focused on Markdown documentation sites that are searchable and mobile-friendly. Docusaurus, Sphinx, and Hugo are alternatives that this source does not compare in detail, so review each one against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Material for MkDocs suits open source maintainers and teams who already write Markdown and want a clean, searchable docs site with little design work. Teams that need long-term support or a no-code builder should evaluate Zensical or another tool first, given the May 5, 2027 end-of-life date.

Install options & downloads