Adam McKay: TIL

Deploying Zola to Cloudflare Pages

#zola#cloudflare

Zola is the static site generator used to power this blog. It’s excellent - easy to use, featureful and fast - however the deployment on Cloudflare Pages isn’t ideal.

Cloudflare Pages documentation says Zola is a supported framework and the UI allows you to select Zola as a framework so it auto populates the build command. However, it appears support for Zola has been dropped in Build System Version 2. The Zola documentation has 2 possible workarounds:

Change the build system version to v1

From within the workers & pages dash, go to the following: Settings > Builds & deployments > Build system version > Configure build system

Then select v1 and save.

Or use UNSTABLE_PRE_BUILD environment variable + asdf

From within the workers & pages dash, do the following: Settings > Environment variables > Edit variables

And add an environment variable UNSTABLE_PRE_BUILD, with the following value and save.

asdf plugin add zola https://github.com/salasrod/asdf-zola && asdf install zola 0.18.0 && asdf global zola 0.18.0

Downgrading to v1 for a new blog isn’t ideal as it will inevitably deprecated at some future point.

Using asdf to install the latest version of Zola works for production deployments but not preview deployments.

Instead I’ve written a small Bash script to use as the build command, which also has the added benefit of allowing drafts to be published on the preview deployment and setting the URL dynamically rather than the fixed value in the production config.toml to ensure absolute URLs work.

#!/bin/bash

# Check if CF_PAGES_BRANCH is set
if [ -z "$CF_PAGES_BRANCH" ]; then
  echo "Error: CF_PAGES_BRANCH environment variable not set. This script is intended to run only in Cloudflare Pages."
  exit 1
fi

echo "Building for branch: $CF_PAGES_BRANCH"

# Install Zola if not already present
if ! command -v zola &> /dev/null; then
  echo "Zola not found, installing via asdf..."
  asdf plugin add zola https://github.com/salasrod/asdf-zola
  asdf install zola 0.18.0
  asdf global zola 0.18.0
fi

if [ "$CF_PAGES_BRANCH" = "main" ]; then
  zola build
else
  zola build --drafts --base-url $CF_PAGES_URL  # Include drafts for preview branches and change base URL for CSS imports
fi
←Top→