Building this site with Hugo and GitHub Pages

At the bottom of each page of this website, it says:

Published with Hugo Blox Builder — the free, open source website builder that empowers creators.

Similar notes can be found on many websites. For someone who is interested in how a particular site was created, that offers a place to start looking. However, it can be easy to become lost in the vast array of resources available for most popular static website generators. Here, I detail exactly how I used Hugo and GitHub Pages, among other tools, to set up the website you’re reading.

Here’s an overview:

• Introduction
• Tools Used
• Installing Hugo
• Setting up the theme
• Installation issues
• Hugo local server
• Editing the site
• Publishing the site
  • Hosting on GitHub Pages

Introduction

Many academics will tell you that having an up-to-date personal website can help you disseminate research and make connections for future projects and career opportunities. I had a personal website hosted through SquareSpace for years. I found it fairly easy to set up initially, and it was simple to make updates. While it was difficult to figure out how to add equations in text and the templates were a bit limiting, it automatically resized the site for all types of devices and I never needed to worry about any backend coding for it. However, at CA$252 a year (circa 2025) for a “Basic” site, I decided I was willing to forego the ease and simplicity of SquareSpace for a free and open source option, Hugo.

I was inspired by a post on Nicole Paul’s website, How did I make my personal academic website?. I share Nicole’s desire to be able to maintain my personal website using a text-based editor. In addition, using Hugo allows me to leverage tools that I am already familiar with to maintain this site, things I use every day like VSCodium, Git, and GitHub.

A big draw for me to use Hugo is that it allows me to launch a local server where I can view my website while it updates live with each change I save in my local repository. This way, I can work on changes and make commits all locally without changing the publicly-viewable version of the site. Then, when I’m satisfied with the changes, I can simply push those commits to the remote repository and the magic of GitHub Actions automatically propagates those changes to the public site.

GitHub provides free hosting through GitHub Pages, however I do pay CA$30.44 a year to Hover for my custom domain name. The whole process of setting this site up had a bit of a learning curve, but I now know how to maintain my own site and I learned a bit of html along the way.

Tools Used

• Hugo
  • An open source web app to generate websites.
• Hugo Blox
  • A group of accessible themes for Hugo sites based on a common set of “blocks” built with either Bootstrap or Tailwind CSS.
• GitHub Pages
  • A platform built in to GitHub through which to host websites.
• GitHub Actions
  • An automation system built in to GitHub, allowing you to have workflows run automatically when certain triggers occur, like a push to the repository.
• Hover
  • A custom domain name provider.

Installing Hugo

Hugo has a page with straight-forward installation instructions. Since I was using a MacBook and already had the Homebrew package manager installed, I first just ran their suggested command: brew install hugo which fairly quickly installed the latest stable version of Hugo (v0.147.9 as of 2025-07-07), which I could double check by running hugo version. However, I immediately ran into a versioning issue. The resolution was to downgrade Hugo to v0.145.0, which I explain how to do below. But, if you’re installing Hugo for the first time and want to use the same academic-cv template as this website does, install Hugo v0.145.0 directly. Your mileage may vary depending the version of Homebrew, but the following command should do the trick:

brew install hugo@0.145.0

If you aren’t interested in using the academic-cv template and just want the latest version of Hugo, checkout the Hugo QuickStart Guide.

Setting up the theme

The theme I chose for my site, academic-cv, is the same as used by Nicole Paul. I decided to follow the Hugo Blox (the makers of the template) documentation page Build your online resume, going to the GitHub page for the academic-cv template and clicking the “Use this template” button to create my own repository for this website. Note that, if you aren’t planning on using a custom domain name for your site, the name you pick for the repository in this step will be part of your published website’s URL.

After creating a repository on GitHub, I went to my terminal and did a git clone in the directory in which I wanted to keep the code on my local machine. Once the repository was cloned, I ran the following command to make sure everything was working:

hugo server

However, I ran into a couple different errors.

Installation issues

Error: failed to init modules: binary with name "go" not found

Error: command error: failed to load modules: module "github.com/HugoBlox/hugo-blox-builder/modules/blox-tailwind" not found

Hugo local server

Hugo allows you to launch a live-updating local instance of your site by navigating your terminal to your site’s repository and running:

hugo server

This will output something like:

Watching for changes in /Users/<your_username>/{Documents,Library}
Watching for config changes in /Users/<your_username>/<repository_path>/config/_default, /Users/<your_username>/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/hugo-blox-builder/modules/blox-plugin-netlify@v1.1.2-0.20231209203044-d31adfedd40b/config.yaml, /Users/<your_username>/Library/Caches/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!hugo!blox/hugo-blox-builder/modules/blox-tailwind@v0.3.1/hugo.yaml, /Users/<your_username>/<repository_path>/go.mod
Start building sites … 
hugo v0.145.0+extended+withdeploy darwin/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=brew


                   | EN  
-------------------+-----
  Pages            | 83  
  Paginator pages  |  0  
  Non-page files   | 43  
  Static files     |  2  
  Processed images | 80  
  Aliases          | 22  
  Cleaned          |  0  

Built in 1381 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) 
Press Ctrl+C to stop

For a particular instance, <your_username> will be your username of on your local machine and <repository_path> will be the path you chose for your local repository. If you open the displayed URL (in this case, http://localhost:1313/) in a browser, you will see what your website looks like. At this point, your terminal will be actively running a local server for your site so if you close it or press Ctrl+C, as mentioned in the output, the server will stop. Note that, if the server stops, the page in your browser will still display until you try to navigate to another page.

While this local server is running, any time you save changes to a file in the repository, the server will auto-update to show the results of the changes. I find this functionality incredibly useful, allowing me to easily test tweaks to my site as I go.

Editing the site

The subsections below detail how I made a lot of the changes on this site. If you are interested in how to get the site live, skip to Publishing the site.

• Site layout
• Changing the date format
• The resume page
  • Adding icons
• Setting the favicon

Site layout

The academic-cv template comes with a number of different sections pre-loaded such as resume, talks, papers, projects, etc. I wasn’t interested in taking the time to fill in every single section before I first made my site live, so I disabled parts of the navigation menu. In the file config/_default/menus.yaml, you can simply comment out the name/url/weight of a menu item to make it not appear in the navigation bar. Note that doing this will not disable the page. If you know the exact url, you can still access it but there won’t be a button to make it discoverable.

Changing the date format

At the top of this page, the date on which this guide was posted is listed. The format of that date, and all other dates on the site, is controlled centrally so that if you want to change the date format, you don’t need to change each page individually. In the config/_default/params.yaml file, there is a block which looks like:

# Localization
locale:
  date_format: '2006-01-02'
  time_format: '15:04'

The Hugo Blox Docs for Localization have a table of acceptable formats for each field (year, month, day, hour, etc.). You can change the date format to whatever you would like, however it is important that the actual date used in the .yaml file is the January second, 2006 at 3:04:05 in the afternoon in Mountain Standard Time. From this forum post on Hugo’s site, I found out that the reason for this comes from the way that the Go language handles datetime objects. The relevant section of the Go language documentation reads:

The reference time used in these layouts is the specific time stamp:

01/02 03:04:05PM '06 -0700

(January 2, 15:04:05, 2006, in time zone seven hours west of GMT). That value is recorded as the constant named Layout, listed below. As a Unix time, this is 1136239445. Since MST is GMT-0700, the reference would be printed by the Unix date command as:

Mon Jan 2 15:04:05 MST 2006

It is a regrettable historic error that the date uses the American convention of putting the numerical month before the day.

The resume page

The main feature of the academic-cv template is the resume. All of the information that appears on the Resume page is stored in the content/authors/admin/_index.md file. Some of the information in that file, such as the “Interests” and “About Me” sections, is loaded on the Home page. One of the first things I did before setting my site live was to change all the information in that _index.md file to be personal to me, as well as replace the content/authors/admin/avatar.jpg image with my own headshot. For sections of the resume that I wasn’t interested in including, I simply commented them out.

Adding icons

Under the skills section of the content/authors/admin/_index.md file, there are references to icons which show up next to each listed skill. If you do not want to display icons next to your listed skills, you can delete or comment out the lines that start with icon:. The Hugo Blox Docs Icons section explains where the site looks for icons depending on what reference you give under each entry. I found the icons I use on my resume page in the following packs:

• Developer icons
• Academicons
• Hero icons

Setting the favicon

A favicon is the little symbol for a website that you will see in various places in your browser. Most commonly, it appears in the tab next to the name of the webpage. The Hugo Blox Docs Website icon section explains that the assets/media/icon.png file is what the site will use as a favicon. For example, this is the favicon for my site:

I used the Favicon Generator site to “Generate From Text” with the following parameters:

• Text: MS
• Font Color: #53D399
• Background Color: #27272A
• Background: Square
• Font Family: Roboto Mono
• Font Variant: Regular 400 Normal
• Font Size: 100

Publishing the site

Being able to view the live-updating site locally is very convenient for testing changes. However, the point of my personal website is to have it publicly accessible. That is where GitHub Pages comes in.

Hosting on GitHub Pages

To connect what I’d built with locally with a publicly accessible host, I followed the guide on how to Host Hugo on GitHub Pages. Funnily enough, that guide was written by the same guy, jmooring (see the screenshot in Step 11), who wrote the instructions for downgrading Hugo with brew I used when having installation issues.

For Step 5 in that guide, the site configuration that is mentioned is, for the academic-cv template, is in config/_default/hugo.yaml, which has the same file name but is different from the file mentioned in Step 7. By taking the time to set up the GitHub Actions described in this guide, your public site should update with your changes every time you push any commits to the remote repository.

You can check the running of your actions by going to the GitHub page for your repository and clicking into the “Actions” tab. If those actions are running correctly, you should be able to now visit a publicly-available version of your site. By going to the “Settings” tab of your GitHub repository (not the “Settings” tab of your GitHub account), and navigating to “Pages” in the sidebar, you should see a notification that your site is live with a button to “Visit Site.” If you aren’t interested in connecting your site to a custom domain, then your setup is done. All you need to worry about now is continuing to edit the site to keep the content up-to-date.