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

Installation

with pip

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 PyMdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

If you're running into problems, read the section on virtual environments.

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:

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

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

Virtual environments

If you're installing Material for MkDocs with pip, the easiest way to make sure that you end up with the correct versions and without any incompatibility problems between packages it to use a virtual environment. First, ensure that you have a Python version of 3 or higher installed:

python --version

If you're good to go, create and activate a virtual environment with:

python -m venv venv
source ./venv/bin/activate

Note that the second venv is the name of the folder where to create the virtual environment – you may choose it as you like. Your terminal should now print (venv) before the prompt and the python executable should be located inside the folder you just created:

which python

Next, install Material for MkDocs with pip, which will download and install all packages in the venv folder you just created, including MkDocs and its dependencies:

pip install mkdocs-material

Verify that MkDocs and Material for MkDocs were both installed correctly:

mkdocs --version
mkdocs serve --help

MkDocs should list material as an option under the --theme flag. When you're finished working with MkDocs, you can exit the virtual environment with:

deactivate