In this post we'll see how to create a themed Zola website, build it with GitHub Actions and deploy it to GitHub Pages, for free.

First let's create a Zola website§

Install Zola on your computer, create the website and go to the new directory

brew install zola
zola init- my-website
cd my-website

Create a GitHub repository§

From the GitHub website, create a new repository dedicated to your new website.

  1. give it a name
  2. a small description
  3. set it to public
  4. skip the last steps so your repo will be empty

Init the repo and push basic files§

On your computer now, let's initiate the git repository, create a basic file, add all the files, commit, specify the proper branch and push to the origin.

git init
echo `Here is my new website powered by Zola, built with GitHub Actions and deployed to GitHub Pages` >
git add *
git commit -m `push all default files`
git branch -M main
git remote add origin
git push -u origin main

Add a theme§

Here we will use ejmg/zerm, the same theme I use for my website.

Specify the theme in the Zola configuration file and add needed plugins.

# The URL the site will be built for
base_url = "/"

# Used in RSS by default
title = "My blog!"
description = "placeholder description text for your blog!"

# The default language, used in RSS
# TODO: I would love to support more languages and make this easy to handle
# with other facets of the theme.
default_language = "en"

# Whether to generate a RSS feed automatically
generate_feed = true
feed_filename = "rss.xml"

# Theme name to use.
# NOTE: should not need to mess with this if you are using zerm directly, i.e. cloning the
# repository at root and not using as directed by the Zola docs via themes/ directory.
# theme = ""

# Whether to automatically compile all Sass files in the sass directory
compile_sass = true

# Whether to do syntax highlighting
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
highlight_code = true

# Syntax highlighting theme. See:
# for more information and themes built into Zola.
highlight_theme = "axar" # Other dark themes that work: "1337", "agola-dark",
                         # "visual-studio-dark"

# Whether to build a search index to be used later on by a JavaScript library
build_search_index = false

# Built in taxonomies of zerm. 
taxonomies = [
           {name = "tags"},
           {name = "categories"},

# Put all your custom variables here
# Many configurations are taken directly from Terminal's config.toml
# ---------------------------------------------------------

# Author name to be added to posts, if enabled.
author = "you!"

# Show author's name in blog post meta data.
show_author = false

# Show categories a blog post is marked with in its meta data.
show_categories = true

# Show tags a blog post is marked with in its meta data.
show_tags = true

# Theme color. You can have any color you want, so long as it's...
# ["orange", "blue", "red", "green", "pink"]
theme_color = "orange"

# Custom css to style over the defaults. This is useful when you only have a
# few small tweaks to make rather than a major rehaul to the theme.
# It would be best to make this a proper .sass or .scss file in sass/ rather
# than placing in static/
# custom_css = "custom.css"

# How many menu items to show on desktop. if you set this to 0, only submenu
# button will be visible.
show_menu_items = 2

# set theme to full screen width.
full_width = false

# center theme with default width.
center = false

# set a custom favicon. Must be placed in root of static/ directory...
# favicon = ""

# Set a custom preview image for your website when posted as a link.
# Must be placed in root of static/ directory...
# og_preview_img = ""

# Copyright notice if desired. Defaults to 
# copyright = "copyright notice here"

# What is displayed in the top left corner of the website. Default is zerm.
logo_text = "zerm"

# Link in logo. Default returns you to $BASE_URL.
logo_home_link = "/"

# Menu items to display. You define a url and the name of the menu item.
# NOTE: `$BASE_URL/` must be included in the url name.
main_menu = [
              {url="/about/", name="about"},
              {url="/contact/", name="contact"},

# Displayed as title of drop-down menu when size of main_menu > show_menu_items.
menu_more = "show more"

# Displayed after teaser text for a blog post.
read_more = "read more"

# not currently used from previous theme, but leaving here for now in case I
# feel like adding it.
read_other_posts = "read other posts"

Create the templates, assets and basic content§

Ejmg's theme use some specific templates, import them

rm -Rf templates/*
cp -Rv themes/zerm/templates/* templates/

Do the same for the assets

mkdir static/assets
cp -Rv themes/zerm/static/assets/* assets/

And for the content too

rm -Rf content/*
cp -Rv themes/zerm/content/* content/

Let's checkout locally if your site is working.

zola serve

Add a workflow for GitHub Actions§

Go to your repository Actions and create a new file.

# On every push this script is executed
on: push
name: Build and deploy GH Pages
    name: shalzz/zola-deploy-action
    runs-on: ubuntu-latest
    # Checkout
    - uses: actions/checkout@master
    # Build & deploy
    - name: shalzz/zola-deploy-action
      uses: shalzz/zola-deploy-action@v0.12.0
        # Target branch
        PAGES_BRANCH: gh-pages
        # Provide personal access token
        TOKEN: ${{ secrets.TOKEN }}

Don't forget to setup a personal access token with the "public_repo" scope, follow the official GitHub documentationm.

Add a CNAME file to setup a custom domain name

echo `` > static/CNAME

Now push all last changes to GitHub

git add *
git commit -m `upload deploy config`
git push

Set up GitHub Pages§

The Action should have been started by now, wait for it to finish and look for a new gh-pages branch being created. When it's done you can set up GitHub Pages.

Go to your repository settings, find the appropriate section and select the gh-pages branch, specify your custom domain and click "Save".

Et voilà! Don't hesitate to reach out to me if you need some help setting this up.