Deploy Hugo Theme exampleSite With Github Actions

Motivation

To test PRs on the upstream of a Hugo theme by setting up a testing branch.

Goal

To deploy a forked GitHub repo for a Hugo theme with exampleSite to GitHub Pages using GitHub Actions.

The whole article is based on my fork of Hugo Future Imperfect Slim.

References

1. GitHub Actions for Hugo
2. A Stack Overflow question showing pwd in GitHub Actions
3. A Hugo Discourse post about testing exampleSite

Difficulties

I had failed for about ten times before I got the job done.

1. Generating a theme’s exampleSite is quite tricky due to the difference in file structure. I used to preview that by

   cd exampleSite
   hugo server --themesDir=../..
   

   Running hugo server --themesDir .. --source exampleSite doesn’t work: .. has to be replaced with ~ so that the command works—that doesn’t work well on remote hosts when the current working path varies from host to host.

2. As a result, I tried to navigate to the parent directory with ${$(pwd)%/*}. That worked well on local Linux shells, but I ran into a bad substitution error. Luckily I found the above linked Stack Overflow question useful.

3. I got lost by switching between GitHub Actions for GitHub Pages and GitHub Actions for Hugo. With the idea that GitLab CI/CD can be migrated to GitHub Actions, I confused GitLab CI/CD’s pages.only with GitHub Actions’ on.push.branches. I jumped to the precautions for first deployment a few times and I mistakenly thought that the source code was on the gh-pages branch. In fact, GitHub Actions takes a branch not named as gh-pages, and generates the static site on gh-pages. The error message "You deploy from gh-pages to gh-pages" was clear enough, so I fixed this quickly.

4. After that, GitHub Actions showed a green tick, indicating that the deploy was successful. I configured my repo to use gh-pages for GitHub Pages. However, when I navigated to the corresponding GitHub Pages, I got a 404 error. gh-pages had one single empty file: .nojekyll. It took me an hour to discover this line on the runner:

   cp: no such file or directory: /home/runner/work/hugo-future-imperfect-slim/hugo
   -future-imperfect-slim/public/*
   

   I then navigated up to find the command used for the build.

   hugo --themesDir "${PWD%/*}" --source exampleSite --minify
   

   I adapted this to my Zsh, and I found that the output was placed under exampleSite/public/. After the correction of publish_dir in GitHub Actions config, everything works.