How to Deploy a Hugo Website via GitHub Pages

There are many ways to deploy a Hugo website. The simplest one perhaps is to host it on Netlify . However, my site deployed by Netlify looks a little bit different from what I see on my local server. So I had to give it up.

I chose to use GitHub Pages. Hugo’s homepage detailed three ways to host a Hugo website though GitHub Pages. The first method is to set up two repositories with one being the submodule. I don’t like the idea of managing two repositories for my website, so I didn’t choose it. The second option , perhaps the easiest one, is to change the publish directory from public to docs, so that GitHub Pages can automatically recognize that the site to deploy is located in the folder of /docs. However, I didn’t like the idea of changing the default publish directory either (Yeah, call me picky if you want).

I chose the third option , which is to set up a new branch called gh-pages which is essentially the public folder. I will document the steps I took to restore my site’s deployment, in case I need to redo it. It may also help others.

Restore the content #

Since I messed it up, I decided to delete all the content. After having deleted everything manually in the root directory, I ran these:

git add .
git commit -m "Deleting everything."
git push origin <master-branch>

The name of my <master-branch> is sources, so I’ll use sources in the following parts.

Then, find out the <commit ID> I want to restore. That should be the one before I messed up everything. Run

git checkout <commit ID> .

As this tutorial said, do not forget the dot after <commit ID>. Also, there is space before the dot.

After that, delete public before pushing everything to sources: rm -rf public. This is because I don’t need public now and if I include it, it will take more time when pushing.

Then, push the restored content to <master branch> branch:

git add .
git commit -m "Restoring."
git push origin sources

Set up gh-pages #

First, delete all the .DS_Store files:

find . -name .DS_Store -print0 | xargs -0 git rm -f --ignore-unmatch
git add .
git commit -m "Remove .DS_Store from everywhere"
git push origin sources

The following steps are based on the official tutorial . I modified it a little bit.

Then, edit .gitignore:

echo "public" >> .gitignore
echo ".DS_Store" >> .gitignore

If you want to edit .gitignore manually, you can use open .gitignore -a TextEdit or open .gitignore -a "Sublime Text".

Then, build and deploy:

rm -rf public
git worktree add -B gh-pages public origin/gh-pages

Regenerate the site and commit the public folder to gh-pages:

hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
git push origin gh-pages

On GitHub, go to Settings → GitHub Pages, then choose “gh-pages”. The site should be running.

Automatic deployment #

The script file provided is a little bit weird, especially the if statement. If it is there, and I added some content to the root directory, then I cannot deploy.

Also, the guidance of Use a Custom Domain provided is a little bit confusing. If I add the CNAME file to the static folder, something will go wrong.

The following script is what I came up with, based on the original one :

#!/bin/sh
MESSAGE="Rebuilding site $(date)"
SOURCE=sources
git add .
git commit -m "$MESSAGE"
git push origin "$SOURCE"

if [ "`git status -s`" ]
then
    echo "The working directory is dirty. Please commit any pending changes."
    exit 1;
fi

echo "Deleting old publication"
rm -rf public
mkdir public
git worktree prune
rm -rf .git/worktrees/public/

echo "Checking out gh-pages branch into public"
git worktree add -B gh-pages public origin/gh-pages

echo "Removing existing files"
rm -rf public/*

echo "Generating site"
hugo

cd public
echo "hongtaoh.com" > CNAME

echo "Updating gh-pages branch"
git add . && git commit -m "Publishing to gh-pages (publish.sh)"

echo "Pushing to github"
git push --all origin

Last modified on 2021-10-05