Deploying MkDocs with Material Insiders theme to Netlify

Published: Last updated:

Some time ago, I wrote a short blog post providing the key info on how to deploy a site using MkDocs and the Material theme theme to Netlify. It's a fairly simple process.

There is another version of the theme, Material Insiders. This version is only available to project sponsors, and contains some nice exclusive features.

However, to access the theme, you have to install it as follows:

pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

In other words, you need to set up a GitHub personal access token, and use it to install the theme from its repo. This ensures only sponsors can access it.

The downside to this is that Netlify (and probably other similar providers) can't access the Material Insiders repo in order to install the theme during build.

There doesn't seem to be a nice way round this. We certainly don't want to start storing GitHub tokens publicly in our repos. This support request suggested a way forward.

Warning: this method works, but it means storing your GitHub token in a Netlify environment variable. Consider the security implications of this. Anyone who can access the site's settings on Netlify can access the token.

Here's what to do:

  1. Follow the guidance here to generate a new token. Make sure you copy the token.

  2. Log in to Netlify, and navigate to Build & Deploy in your site's settings.

  3. Scroll down to Environment.

  4. Select New variable (or Edit variables > New variable if you already have other variables).

  5. Enter GH_TOKEN as the Key, and your GitHub token as the Value.

  6. Select Save.

  7. Open your netlify.toml (or create one), and add the following:

    [build]
        command = "pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git p && mkdocs build"
        publish = "site"
    
  8. If you are only using the Material theme (and the dependencies it includes, such as MkDocs), you can delete your requirements.txt.

  9. Add a runtime.txt, setting your Python version to 3.x (otherwise Netlify uses 2.7). Do not specify a patch version:

    3.7
    
  10. Push your changes to GitHub. If everything has worked, Netlify should now automatically use the Insiders theme for its builds. You can check this by opening a pull request and reviewing the preview build.