Deploy Hugo Theme exampleSite With Github Actions


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


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.


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


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

    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.

No comment

Your email address will not be published. Required fields are marked *.