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.

Add three files

Add these three files to the root of your project:

In my files, I have the following:

# requirements.txt
mkdocs==
mkdocs-material==
# runtime.txt
# don't specify a patch version, such as 3.7.6
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.