Getting started¶

Method	Description	One	Two	Three	Four	Five
`GET`	Fetch resource	name one two three	one	two	three	four
`PUT`	Update resource	name	one two three four	three	four	five
`DELETE`	Delete resource	one	two	three	four	five six seven eight nine `ten`

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 recommend using docker.

Installation¶

with pip recommended¶

Material for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. If not, scroll down and expand the help box. Install with:

HTML for content and structure
JavaScript for interactivity
CSS for text running out of boxes
Internet Explorer ... huh?

Set up in 5 minutes

Install mkdocs-material with pip and get up and running in minutes

Getting started
It's just Markdown

Focus on your content and generate a responsive and searchable static site

Reference
Made to measure

Change the colors, fonts, language, icons, logo and more with a few lines

Customization
Open Source, MIT

Material for MkDocs is licensed under MIT and available on GitHub

License

Hover me

Latest8.x

pip install mkdocs-material

pip install mkdocs-material=="8.*" # (1)!

Material for MkDocs uses semantic versioning¹, which is why it's a good idea to limit upgrades to the current major version.

This will make sure that you don't accidentally upgrade to the next major version, which may include breaking changes that silently break your site. Additionally, you can use pip freeze to create a lockfile, so builds are reproducible at all times:
```
pip freeze > requirements.txt
```
Now, the lockfile can be used for installation:
```
pip install -r requirements.txt
```

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.

Tip: If you don't have prior experience with Python, we recommend reading Using Python's pip to Manage Your Projects' Dependencies, which is a really good introduction on the mechanics of Python package management and helps you troubleshoot if you run into errors.

with docker¶

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:

Latest8.x

docker pull squidfunk/mkdocs-material

docker pull squidfunk/mkdocs-material:8

The 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 only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, create a new Dockerfile and extend the official Docker image:

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 arm64 or armv7, as it is automatically built on every release:

docker pull ghcr.io/afritzler/mkdocs-material

with git¶

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 -e mkdocs-material

Note that improvements of existing features are sometimes released as patch releases, like for example improved rendering of content tabs, as they're not considered to be new features. ↩