Deploying MkDocs with Material theme to Netlify

Published: Last updated:

MkDocs is a Python-based static site generator, designed for building documentation sites. It's a personal favourite. I use it for my some of my own projects (including the Tech writer toolkit, using the fantastic Material theme), as well as for client work.

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

Note: this guide assumes you are using the public release of the Material theme. If you are using the Insiders release, it gets more complicated. Refer to Deploying MkDocs with Material Insiders theme to Netlify for one possible approach.

Add three files

Add these three files to the root of your project:

In my files, I have the following:

# requirements.txt

# runtime.txt
# don't specify a patch version, such as 3.7.6
# netlify.toml
  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 I usually use a basic continuous deployment pipeline:

  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 to deploy with git.

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.