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.
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.
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.
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).
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.
netlify.toml: contains your site settings. If your site uses a custom output directory name, replace
sitewith the value of
For the free version of Material:
For Material Insiders:
- On the Team overview 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
- 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.
- 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:
- Navigate to Build & Deploy in your site's settings.
- Scroll down to Environment.
- Select New variable (or Edit variables > New variable if you already have other variables).
GH_TOKENas the Key, and your GitHub token as the Value.
- 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.