Skip to content

Cloudflare Pages

Last updated: 10th September 2023

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
  • Are using version 2 of the Cloudflare Pages
  • If you are using Insiders, you have set up a personal access token.

Site setup

If you want to use a non-default version of Python, add a runtime.txt to the root of your project. Refer to Cloudflare's info about build images and versions for more information.

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

1
mkdocs-material==<YOUR_MATERIAL_VERSION>

Deployment

  1. In your Cloudflare dashboard, select Pages.
  2. Select Create a project > Connect to Git. 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. If 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: 
        1
        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.

Hire me for a docs consultation