mkdocs-material/docs/getting-started.md

template
overrides/main.html

Getting started

Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familar 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:

=== "Community edition"

``` sh
pip install mkdocs-material
```

=== "Sponsor edition"

``` sh
pip install git+https://$GH_TOKEN@github.com/squidfunk/mkdocs-material-next.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 the sponsor edition, 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:

docker pull squidfunk/mkdocs-material

The mkdocs executable is provided as an entry point and serve is the default command. If you're not familar with Docker don't worry, we have you covered in the following sections.

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:

=== "Community edition"

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

=== "Sponsor edition"

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

The theme will reside in the folder mkdocs-material/material. Note that when cloning from git, you must install all required dependencies yourself:

pip install -r mkdocs-material/requirements.txt