Deploying MkDocs with Material theme to Netlify

Key points when deploying MkDocs projects to Netlify.

Published: 15-02-2020

MkDocs is a Python-based static site generator, designed for building documentation sites. It's a personal favourite. I use it for my own projects (including the Tech writer toolkit, using the fantastic Material theme) and even for this website.

Deploying to Netlify is pretty straightforward, but there are a few things to look out for.

Add three files

Add these three files to the root of your project:

  • requirements.txt: this will list software dependencies and versions.
  • runtime.txt: tell Netlify which Python version to use.
  • netlify.toml: contains some site settings.

In my files, I have the following:

# requirements.txt
mkdocs==1.0.4
mkdocs-material==4.6.3
# runtime.txt
# don't specify a patch version, such as 3.7.6
python 3.7
# netlify.toml
[build]
  command = "mkdocs build"
  publish = "site"

If you don't specify the Python version, Netlify tries to use Python 2.7, which causes errors and the build fails.

Then deploy

Now you can deploy as usual. Your process may vary depending on your setup, but broadly:

  1. Push your changes to your remote repo (GitHub / GitLab / Bitbucket) and merge to master, or your deployment branch.
  2. In Netlify, select New site from Git and walk through the process of linking your remote repo to Netlify.

And that should be it. Your site should build, and be available at a preview link (find the link in Settings > Domain management > Domains).

If there are problems, look at the deploy logs:

  1. Select Deploys.
  2. Select the latest deployment.