Zola on github Pages

Deploy your Zola generated website to github pages

3 min 505 words
Thomas Chartron


Deploy a zola site to GitHub pages

This will explain how to deploy a website created with Zola SSG to github pages and host it for free.


  • Github account
  • Ready to deploy Zola website (as git repository)
  • (Optional) Domain name


  1. Create a github reposity with this form : .github.io and make it public
  2. Create a simple README.md file to describe your project.
  3. Add this repository which will be used to host the website as a git submodule of your Zola website.
cd my-zola-website
git submodule add -b main git@github.com:<username>/<username>.github.io.git public

This added the repository we created as a submodule in the public folder.

  1. Now go back to the root of the Zola website and copy this script as deploy.sh and make it executable
cd ..
touch deploy.sh

#deploy.sh content
#!/usr/bin/env bash

# If a command fails then the deploy stops
set -e

if [ -d "public" ]
    echo -e "\033[0;32mRemoving public folder except .git and README.md and CNAME \033[0m\n"
    cd public
    find . -not -name '.git' -not -name 'README.md' -not -name 'CNAME' -delete
    cd ..

echo -e "\033[0;32mDeploying updates to GitHub pages repository\033[0m\n"
# Build the project to another directory because zola will delete the submodule /public otherwise
zola build --output-dir public_zola
#Now copy built files to public directory
cp -a public_zola/ public/
rm -rf public_zola

echo -e "\033[0;32mCommit change to main repository\033[0m\n"
git add .
git commit -am "update"
git push origin main

# Go To Public folder
cd public

git checkout main
# Add changes to git.
git add .

# Commit changes.
msg="update site content $(date)"
if [ -n "$*" ]; then
git commit -m "$msg"
# Push source
git push origin main
  1. Now deploy your website to https://.github.io with this simple command : ./deploy.sh "update site content". This will remove the previous version of the website locally, then commit all changes

Set up a custom domain name

  1. Go to your domain name provider DNS zone configuration
  2. Add A entry pointing to one of github pages IP addresses : list here
  3. In your github .github.io repository go to Settings >> Pages >> In Custom Subdomain enter subdomain (example : mydomain.com)
  4. In you DNS zone configuration i recommend adding another entry to use www.mydomain.com also.
  5. Add CNAME entry example : www.mydomain.com >> .github.io. (don't forget final dot for absolute notation)


If a submodule was previously added and throws an error like : "A git directory for 'public' is found locally with remote(s)" you can do this

rm -rf public
# Delete the relevant lines from the .gitmodules
git rm -r --cached public
rm -rf .git/modules/public
# Then re add the submodule
git submodule add -b main git@github.com:<username>/<username>.github.io.git public