Netlify

Last updated: 6th April 2025

Netlify offers hosting for static sites (as well as a range of Jamstack services). You can connect your git repo (GitHub, GitLab, or Bitbucket) to set up automated deploys, including preview builds on pull request.

This post walks through deploying an MkDocs site with the Material theme.

There are some differences between deploying a site with the free Material theme, and one using Material Insiders (accessible to sponsors). This guide covers both.

Prerequisites

I've assumed you:

Have an MkDocs site using the Material theme
Are using GitHub as your remote repo (but the process should be very similar for GitLab or Bitbucket)
Have a Netlify account
If you are using Insiders, you have set up a personal access token.

Site setup

Add these files to the root of your project:

requirements.txt: this will list software dependencies and versions. You should leave this out if using Insiders (assuming you have no other dependencies).
1
mkdocs-material==<YOUR_MATERIAL_VERSION>

netlify.toml: contains your site settings. If your site uses a custom output directory name, replace site with the value of site_dir from your mkdocs.yml.
For the free version of Material:

# netlify.toml
[build]
  command = "mkdocs build"
  publish = "site/"
  environment = { PYTHON_VERSION = "<YOUR_PYTHON_VERSION>"}

For Material Insiders:

# netlify.toml
[build]
    command = "pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git && mkdocs build"
    publish = "site/"
    environment = { PYTHON_VERSION = "<YOUR_PYTHON_VERSION>"}

Deployment

On the Sites page, select Add new site > Import an existing project.
Choose your git provider. If it is your first time using Netlify, it will take you through an authentication process. Make sure you allow Netlify to access the repo you want to deploy. Once your git provider is connected, Netlify displays the Pick a repository from page.
Choose the repository you want to deploy.
Netlify loads build and deployment settings from your netlify.toml. Check that the Branch to deploy, Base directory, Build command and Publish directory are correct.
If using Insiders:
Under Environment variables, select New variable.
Enter GH_TOKEN as the Key, and your GitHub token as the Value.
Select Deploy .

Your site should now be live and available at Netlify's autogenerated preview link.

Refer to the documentation for information on next steps, including adding a custom domain.

Your Product Needs Words

Explore Services Contact Me