Skip to content

Cloudflare Pages

Cloudflare Pages provide automated deployments (and preview builds on pull request) for static sites. It works with GitHub and GitLab.

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)
  • Have a Cloudflare account
  • If you are using Insiders, you have set up a personal access token.

Site setup

Add a runtime.txt to the root of your project. Don't specify a patch version or language, such as python-3.7.0. 3.7 is the currently supported version.

3.7

Note

Cloudflare Pages uses Netlify's build image. It seems Cloudflare are using the older image, "xenial", meaning 3.7 is the highest available Python version. If they start using "focal", 3.8 will become the default Python version, and you will need to update your runtime.txt.

If you are using the free version of Material, add a requirements.txt to the root of your project:

mkdocs-material==<YOUR_MATERIAL_VERSION>

Deployment

  1. In your Cloudflare dashboard, select Pages.
  2. Select Create a project. If this is your first time using Pages, go through the process to link you GitHub account. Make sure you allow access to the repo you want to deploy. Once GitHub is connected, Cloudflare shows the Deploy a site from your account page.
  3. Choose the repository you want to deploy. Select Begin setup.
  4. on Set up build and deployments, enter the build settings:
    • Check the Project name and Production branch are correct.
    • If you are using the free version of Material, and have not changed the output directory of MkDocs, select MkDocs in Framework preset. You are ready to deploy.
    • If you are using Insiders:
      • Enter a custom Build command:
        pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git && mkdocs build
        
      • Enter site (or the value of site_dir if your site uses a custom output directory name) as the Build output directory.
      • Select Environment variables (advanced) > + Add variable.
      • Set Variable name to GH_TOKEN, and enter your GitHub personal access token as the Value. You are ready to deploy.
  5. Select Save and deploy. Cloudflare builds your site. This may take a few minutes.
  6. Once the build and deployment is complete, you can view your site at the autogenerated preview link: from the site dashboard, select Visit site.

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