Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with
pip, the Python package manager. If not, we recommended using
In case you're running into problems, consult the troubleshooting section.
with pip recommended¶
Material for MkDocs can be installed with
pip install mkdocs-material
This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.
The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Pull the image for the
latest version with:
docker pull squidfunk/mkdocs-material
mkdocs executable is provided as an entry point and
serve is the default command. If you're not familiar with Docker don't worry, we have you covered in the following sections.
The following plugins are bundled with the Docker image:
How to add plugins to the Docker image?
Material for MkDocs bundles useful and common plugins while trying not to blow up the size of the official image. If the plugin you want to use is not included, create a new
Dockerfile and extend the official Docker image with your custom installation routine:
FROM squidfunk/mkdocs-material RUN pip install ...
Next, you can build the image with the following command:
docker build -t squidfunk/mkdocs-material .
The new image can be used exactly like the official image.
Apple Silicon (M1) and Raspberry Pi
The official Docker image is only available for
linux/amd64. We recommend the third-party image by @afritzler if you want to run Material for MkDocs via Docker on
armv7, as it is automatically built on every release:
docker pull ghcr.io/afritzler/mkdocs-material
Material for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:
git clone https://github.com/squidfunk/mkdocs-material.git
The theme will reside in the folder
mkdocs-material/material. When cloning from
git, you must install all required dependencies yourself:
pip install -r mkdocs-material/requirements.txt