mkdocs-material/docs/getting-started.md

template	title
overrides/main.html	Getting started

Getting started

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

In case you're running into problems, consult the troubleshooting section.

Installation

with pip

Material for MkDocs can be installed with pip:

=== "Material for MkDocs"

```
pip install mkdocs-material
```

=== "Insiders"

``` sh
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```

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.

Note that in order to install Insiders, you'll need to become a sponsor, create a personal access token¹, and set the GH_TOKEN environment variable to the token's value.

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:

=== "Material for MkDocs"

```
docker pull squidfunk/mkdocs-material
```

=== "Insiders"

```
docker login -u ${GH_USERNAME} -p ${GH_TOKEN} ghcr.io
docker pull ghcr.io/squidfunk/mkdocs-material-insiders
```

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:

• mkdocs-minify-plugin
• mkdocs-redirects

Note that in order to install Insiders, you'll need to become a sponsor, create a personal access token², and set the GH_TOKEN environment variable to the token's value.

??? question "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:

``` Dockerfile
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.

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:

=== "Material for MkDocs"

```
git clone https://github.com/squidfunk/mkdocs-material.git
```

=== "Insiders"

```
git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
```

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

Note that in order to install Insiders, you'll need to become a sponsor.

---

1. In order to use pip to install from the private repository over HTTPS, the personal access token requires the repo scope. The creation and usage of an access token is only necessary when installing Insiders over HTTPS, which is the recommended way when building from within a CI/CD workflow, e.g. using GitHub Pages or GitLab Pages. ↩︎

2. If you want to use docker to pull the private Docker image from the GitHub Container Registry, the personal access token requires the read:packages scope. Note that you need to login before pulling the Docker image. As an example, see the publish workflow of the Material for MkDocs repository. You'll also need to enable "Improved Container Support" on your account. ↩︎