zola-cloudflare-pages

First look at running a Zola static website on Cloudflare Pages while using Nix for a development environment.

Getting Started

  1. Install dependencies and get ready to run:

    nix develop

  2. Start the Zola development server:

    zola --root zola serve

    Visit http://127.0.0.1:1111 to see the site. The server will automatically reload when you make changes.

How this works

You need nix installed. Running the nix develop command will install zola and download the anemone theme. The zola serve command runs a local version of the site. It will update as you edit files and write content.

nix --version
nix (Nix) 2.25.4

The theme is copied (not symlinked) because Cloudflare Pages needs all files to be committed to the repository. If you were building locally or in a GitHub Action instead, you could use a symlink.

Cloudflare

Login to Cloudflare, go to Compute (Workers), make a new application. Choose pages. Run through the setup for linking it to a GitHub repository.

The good

Cloudflare watches your repo. They build and deploy for you so you don't need a GitHub workflow.

When you get a green build, you'll be given a pages.dev subdomain to use.

If you are using a custom domain then be sure to set it in Zola's base_url in 'zola/config.toml'. I added a CNAME to my afharvey.com domain like this:

CNAME zola zola-cloudflare-pages.pages.dev

See https://zola.afharvey.com

Note: I also use Cloudflare for DNS and I ticked the "Proxied" check box.

The bad

If you see an error about zola not being found then change to the version 1 build system and set the ZOLA_VERSION. See the 'wrangler.toml' file. As of January 2025, a quick search shows lots of issues where people have run into this. I got it working, but it's unfortunate I can't use the Cloudflare v2 build system.

Note: Remember to set ZOLA_VERSION under both Production and Preview in the "Choose Environment" drop down.

Tools