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.

Installation

!!! danger "8.0.0 Beta 2 is out!"

Help test the latest version of Material for MkDocs, introducing many new
features and improvements like [code annotations], [anchor tracking] and
[version warnings]. See #3219 for installation and upgrade instructions.

with pip recommended

Material for MkDocs can be installed with pip:

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.

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:

docker pull squidfunk/mkdocs-material

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

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

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

!!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: 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