Deploy a Zola site to GitHub Pages

There are a thousand different static site generators out there and I have probably tried them all by now. Over the years, I kept coming back to Hugo, because it’s solid, reliable, and has a huge community. But I was never a big fan of the Go-flavored templating language or some of the confusing conventions.

Lately I have been turning to Zola for new static site projects. Zola is a static site generator in the style of Hugo, but written in Rust 🦀. It’s simpler and faster, is also a available as a single portable binary, and uses the templating language Tera. While not as popular as Hugo, Zola is supported by many of the “just push to deploy”-platforms (eg. GitHub Pages, Netlify, Render, Cloudflare Pages, etc.) that take the hassle out of hosting static sites.

So when I recently had to put together a quick static site for the Copenhagen Rust Community, it was the obvious choice.

The deployment instructions in the Zola docs reference the traditional GitHub Pages deployment method. But last year, GitHub introduced custom Actions workflows for GitHub Pages and I wanted to try that method instead.

Since there was no premade workflow template for Zola sites, I copied the suggested workflow for Hugo and adapted it. I thought I would share it, in case someone needs it.

Instructions #

Step 1 #

Go to the Settings tab of your repository, and find Pages in the sidebar.

In the Source dropdown, choose GitHub Actions. Then click Create your own.

The Pages section in the Settings tab

Step 2 #

Name the file deploy.yml and paste in the following workflow configuration:

deploy.yml · YAML

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


name: Deploy to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
        ZOLA_VERSION: "0.17.2"
    steps:
      - name: Install Zola
        run: |
          set -x
          wget -O - \
            "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
          | sudo tar xzf - -C /usr/local/bin          
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Build with Zola
        run: |
                    zola build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Make sure to update options like branches:, path:, and ZOLA_VERSION to match your preferences before you save.

Step 3 #

The Actions workflow will run automatically and you can inspect the progress in the Actions tab of your repository page.

The Summary section of GitHub Actions

Once configured, any commits pushed to the branch will trigger a build and a deployment of the hosted GitHub Pages site.