Skip to content

Netlify

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>
  • runtime.txt: tell Netlify which Python version to use. Don't specify a patch version or language, such as python-3.8.0. If you don't specify the Python version, Netlify tries to use Python 2.7, which causes errors and the build fails. 3.8 is the currently supported version. 
    1
    3.8
  • 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: 
    1
2
3
4
    # netlify.toml
[build]
  command = "mkdocs build"
  publish = "site"

For Material Insiders:

1
2
3
[build]
    command = "pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git && mkdocs build"
    publish = "site"

Deployment

  1. On the Team overview page, select Add new site > Import an existing project.
  2. 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.
  3. Choose the repository you want to deploy.
  4. 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.
  5. Select Deploy site.

If you are using the free version of Material, your site should now be live and available at Netlify's autogenerated preview link (find the link in Settings > Domain management > Domains). If you are using Insiders, builds will fail until you provide your GitHub personal access token:

  1. Navigate to Build & Deploy in your site's settings.
  2. Scroll down to Environment.
  3. Select New variable (or Edit variables > New variable if you already have other variables).
  4. Enter GH_TOKEN as the Key, and your GitHub token as the Value.
  5. Select Save.

Warning: this environment variable is visible to anyone with access to the site on Netlify. Consider the security implications of this. Anyone who can access the site's settings on Netlify can access the token.

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