I’ve started a personal website, based on Hugo’s hello-friend-ng theme by Djordje Atlialp. Learning Hugo as a side project has been interesting, and these are my notes to return to if I forgot anything. Your experience may vary especially if your architecture is different (I’m using GitHub Pages with a Custom Domain and on macOS) but I’d be glad if these are of use to you.

The website is designed using Hugo, a static website generator. I was fiddling a lot with WordPress and LightSail previously, but eventually decided that this was best for me as:

  1. I don’t have the time to deal with all the server-side jazz that comes with a WordPress setup, and won’t be using much of it anyway.
  2. Everything is written in markdown which keeps things simple.
  3. Hugo is fast, has many themes to choose from, allows for future expansion, etc.

Setup the Website

Everything from here assumes that:

  1. Hugo is installed using, for example, homebrew.
  2. Git is installed.
  3. We have a GitHub account.

First, make the site using Hugo’s built-in command new site in Terminal. This creates a new folder with the necessary (base) files in the directory we’re currently in:

hugo new site your-site-name
cd your-site-name

We also want to make this a new local git repo:

git init

Add theme

Then, we add the theme as a submodule into the website’s /themes folder. Assuming extensive customization is not performed, adding the theme as a submodule allows us to easily get theme updates, and is the best option.

git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng

At this point, we can experiment by adding pages and posts, editing the home page, etc. To see how it looks, type hugo server in Terminal and visit http://localhost:1313/ in a web browser.

Additional to edits of our preference, there are two important configurations to the site’s config.toml file that must be made before moving on:

  1. To prevent issues with the site’s look later, to the file’s top line, add either:

    1. If not using a custom domain, but using a GitHub Pages project site, add baseURL = https://<username>.github.io/<repo-name>/, changing out <username> to the GitHub username, and repo-name to the intended name of the GitHub repo that this will be uploaded to (which we’ll create later).
    2. If not using a custom domain, but using a GitHub Pages user site, add baseURL = https://<username>.github.io, changing out <username> to the GitHub username.
    3. If using a custom domain, add baseURL = https://<custom-domain-name>/.

  2. Add the line publishDir = "docs". When we build the site later using Hugo, it will therefore build to the website’s /docs folder. The website’s actual files are thus separated from the files Hugo uses to build the website. (These files are overwritten whenever we update and then rebuild the site.)

Build the site with hugo

Once ready, build the site:

hugo

As per earlier, this populates the website’s /docs folder with the necessary files.

Add and commit all additions

Add (-a) and commit (-c) all additions, and include the summary message of our preference (e.g., -m "Create site").

git commit -a -m "Create site"

Create, connect, and push to a new GitHub repo

We’ve now got a local git repo with all items committed, and we can use it locally. However, to host the site on GitHub we need it to have a home there.

  1. Go to GitHub and login.
  2. Create a new repo.

In the quick setup dialog after creating the repo, follow the instructions for pushing an existing repo from the command line:

git remote add origin https://github.com/<username>/<new-repo-name>.git
git branch -M main
git push -u origin main

This creates a connection to the remote GitHub repo1, creates a branch named “main” on that repo2, and uploads the local repo’s committed content to the remote GitHub repo3.

Note that if we are using a GitHub Pages user site, the name of the new repo <new-repo-name> must be the same as the GitHub username. (This makes it a special repo.)

Configure Github Pages to serve the site

To activate GitHub Pages for the repo we need to go to its Settings > Pages section and configure it as per the screenshot. Recall that Hugo has built the site’s actual files into the /docs folder, hence the below. (Ignore the “Theme Chooser” portion as we are not using Jekyll, but Hugo’s static site generator.)

ss1

At this point, we can actually check the deployment by navigating to the root of the repo (github.com/<username>/<repo name>), clicking “github-pages” under “Environment” on the right hand tab, and then clicking “View deployment” like below:

ss2

However, do note that if the config.toml file does not have the appropriate baseURL = <url> line at the top (e.g. it has the custom domain when we haven’t yet set it up), the look of the site might be a bit wonky.

Setup a Custom Domain (to Point to the Website)

This largely follows GitHub’s instructions; the documentation is helpful. Here, I retrace my steps in configuring an apex domain together with the www subdomain variant.

Configure the apex domain

The apex domain is something like example.com. To do this, we have to do two things:

First, on GitHub’s end, go into the repo’s “Pages” settings:

ss3

And enter the custom domain under “Custom domain” and click “Save”. As per GitHub’s documentation, this creates a commit that adds a CNAME file in the root of your publishing source (i.e., in /docs, if we followed the previous section).

Second, on the DNS provider’s end, create an A record that points the apex domain to GitHub Pages' IP addresses. As of August 2020, this was:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Configure the www subdomain variant

Again on the DNS provider’s end, create a CNAME record pointing www.example.com to the default domain for the site. Note that even if you are using a GitHub Pages project site, the record should point to https://<username>.github.io, and not https://<username>.github.io/<repo-name>.

Conclusion

And that’s it! I’ll update this post if there are any future changes, but I hope this was helpful for now.

  1. The command git remote allows us to create/delete/view connections to other repositories; add origin https://github.com/<username>/<new-repo-name>.git adds a remote connection to the GitHub repo in the URL. ↩︎

  2. The command git branch allows us to create/delete/list/rename branches; -M main is the message that names the branch “main”. ↩︎

  3. The command git push uploads the (committed) local repo’s content to the remote (GitHub) repo, -u sets up the tracking reference for the branch we are pushing upstream in conjunction with origin main, which pushes to the main branch in origin. This is a helpful link. ↩︎