Local installation

In order to preview MkDocs as you write, you will first need to run MkDocs locally with Docker.

Warning

The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

Install 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. Open up a terminal and pull the image with:

Latest9.x

docker pull squidfunk/mkdocs-material

docker pull squidfunk/mkdocs-material:9

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

Warning

The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

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, you can add them easily following the add plugins to the Docker image section below.

Verify required plugins

Be sure to include the plugins that are installed in the 'publish-pages' workflow. Look in the repos .github/workflows/publish-pages.yml file for commands starting with pip install for needed MkDocs plugins.

Add plugins to the 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, you can add them easily:

Material for MkDocsInsiders

Create a Dockerfile and extend the official image:

Dockerfile

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-awesome-nav
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-git-revision-date-localized-plugin
RUN pip install mkdocs-git-committers-plugin-2

Clone or fork the Insiders repository, and create a file called user-requirements.txt in the root of the repository. Then, add the plugins that should be installed to the file, e.g.:

user-requirements.txt

mkdocs-awesome-nav
mkdocs-macros-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-git-committers-plugin-2

Verify correct list of plugins

Be sure to include the plugins that are installed in the 'publish-pages' workflow. Look in the repos .github/workflows/publish-pages.yml file for commands starting with pip install for needed MkDocs plugins.

Build the Docker image

Next, build the image with the following command:

docker build -t squidfunk/mkdocs-material .

The new image will have additional packages installed and can be used exactly like the official image.