A Quick Guide for Hosting a Hugo Site on GitHub

In working with my son on a project to host a Hugo web site on GitHub, it was clear that the many steps involved to accomplish this were documented but spread out among many different pages on the Web. This is an attempt to bring a number of those resources together to reduce the effort for the future.

As a point of explanation, I will be focusing on hosting a Hugo web site using GitHub Pages for a specific user. There are other options for hosting a Hugo web site for a repository and some of the details for hosting a web site for a repository will be similar, but I won’t go into those details.

Documentation Conventions

Before I start here are a few conventions to be aware of below. You will see the following admonitions in the document:

💡
 This provides a suggestion or tip.
ℹ️
 This represents an informational note.
❗
 This is information that is considered "important".

Software Installation

For this effort, there are a few things that need to be installed on the Hugo web site development computer to make life a little easier.

First, I should note that these instructions are specifically for developing the Hugo site under Linux. You can use Windows Subsystem for Linux or Linux running in various other environments to perform the work. The instructions will be provided assuming a more command-line environment with basic utilities than an environment using a lot of GitHub-specific tools.

Assuming a fairly typical Linux installation with OpenSSH already installed, I would recommend installing both Hugo and Git. Under an Ubuntu-like environment, this can be done as follows:

sudo apt install hugo git

Under a Fedora-like environment, these can be installed as follows:

sudo dnf install hugo git

SSH Configuration

Once the basic software is installed, I would recommend setting up your SSH environment to make it easier to push commits to GitHub from the command line. This requires a few steps.

Generating SSH Keys

First, generating an SSH public-key/private-key pair will be necessary, if you don’t have one already. This can be done by running:

ssh-keygen

More options can be provided to specify specific key types and other details, but the defaults are generally fine.

❗
 I highly recommend defining a passphrase for the private key for added security.

Adding the SSH Key to Your GitHub Profile

Once you have a key pair generated, you will need to take the public key (for example, ~/.ssh/id_rsa.pub) and install it in your GitHub profile. After doing this, GitHub will be able to let you authenticate connections to GitHub using your SSH key.

Setting Up SSH Agent

If you are running in desktop Linux (I generally do) or some other environment where an SSH agent is already running, you don’t need to do the following. From a pure command-line environment (for example, under WSL or working remotely on some Linux machine), you can setup an SSH agent environment as follows:

ssh-agent bash

This runs a new bash shell with an SSH agent environment. Why is this useful? By using SSH aent, you only need to enter your SSH passphrase once per login session as opposed to having to provide the passphrase every time you need to use your SSH keys. This is very convenient while still using a secure means of accessing resources and repositories on GitHub or other locations.

Adding Your SSH Keys to the SSH Agent

Once the SSH agent is up and running, you need to do the following so that the agent can remember your keys for you during the command-line session:

ssh-add

You will be prompted for your passphrase for your private SSH key and then the credentials will be cached by the SSH agent for future uses.

You will want to setup the ssh-agent and perform ssh-add every time you start a new shell or have a new desktop login session. If you are still using the same session, you don’t need to repeat these steps.

Test the SSH Connection to GitHub

I would recommend following the instructions found in Testing Your SSH Connection on GitHub to test your GitHub connectivity. This is necessary before proceeding the next steps.

Setting Up a GitHub Repository for Hosting the Hugo Site

Next, you can follow instructions for hosting a Hugo site using GitHub Pages. I will describe the process a little more here.

To begin with, you will want to create a repository for the Hugo web site with the following name: <username>.github.io, where <username>, of course, is the name of the GitHub account (see Types of GitHub Pages Sites) for more information.

ℹ️
 The following instructions assume that the repository is not actually initialized.

Create your Local Hugo Site

With a place to put the repository on GitHub, you can now create your Hugo site as follows (based on the Quick Start instructions for Hugo):

  1. Create your directory for where you want to keep your files, e.g.:

    mkdir src/hugo

  2. Change directories to the new directory, e.g.:

    cd src/hugo

  3. Run the hugo command to get the site initialized:

    hugo new site myusername.github.io

    where myusername.github.io should be replaced with the appropriate site name.

  4. Change directories into the newly created Hugo site directory, e.g.:

    cd myusername.github.io

  5. Initialize the directory as a Git repository:

    git init

    1. You might be asked to setup your username and email for the repository. Just follow the provided instructions as provided by the git command.

  6. Change the name of the master branch to main

    git branch -M main

    This is not strictly necessary, but will reduce the amount of changes expected relative to the default configuration described in Hugo Host on GitHub page.

  7. Setup the theme you want to use for the site. You can do this in a few ways.

    1. Ideally, you can clone the theme right into your project as a Git submodule so you can easily update the theme based on changes made on the original repository. From the Quick Start instructions, here is an example:

      git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

      1. If the above doesn’t work for you, you might try opening up a terminal in the repository for the new Hugo site (e.g., myusername.github.cio) and re-run the command. We saw some issues running git submodule in putting things together initially, though, I was also able to do it successfully just now.

    2. If the above doesn’t work, you can do the following (not ideal):

      cd themes
git clone https://github.com/theNewDynamic/gohugo-theme-ananke
mv gohugo-theme-ananke ananke
cd ananke
rm -rf .git

      This effectively clones the repository, but removes the git repository information so it can be included in the local repository directly.

    3. Add the theme information to your config.toml file:

      echo "theme = 'ananke'" >> config.toml

      or add it by hand with your favorite editor. Of course, update the name of the theme, as appropriate.

  8. Update the baseURL field in the config.toml file to reflect the actual site URL. For example, following the example in this article, the baseURL should be as follows:

    baseURL = 'https://myusername.github.io/'

  9. At this point, you can run the following to test the configuration:

    hugo server

    and browse to http://localhost:1313/. I would resolve any issues if hugo server is not working as expected before going on to the next steps.

Setting Up the Repository for GitHub Actions

As described in the Host on GitHub page for Hugo, you need to create a file named .github/workflows/gh-pages.yml relative to the root of your Hugo repository. The contents, as of this writing, is recommended to be:

name: github pages

on:
  push:
    branches:
      - main  # Set a branch that will trigger a deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

What this does is setup automated GitHub actions that will build/rebuild your site when changes are committed to the repository on GitHub.

💡
 If you continue to use the master branch instead of main, you will need to replace both instances of main with master in the file above.
ℹ️
 The Ananke theme requires the extended version of Hugo, so the extended: true setting is uncommented in the above configuration file.

Push the Repository to GitHub

Assuming you have setup your SSH environment as described in [SSH Configuration] (meaning you are currently running an ssh-agent and have registered your private key with the agent using ssh-add), you can do the following to push your Git repository to GitHub:

  1. Make sure you do a git add all of the files in the repository.

    1. In the top-level directory for the repository, myusername.github.io, you could run

      git add .
      ℹ️
      		 I don’t recommend committing .hugo_build.lock. That doesn’t seem to be something that should be in the repository. If it exists and gets added, you can run the following: 
      git rm --cached .hugo_build.lock

      from the top-level directory to remove it from being staged.

    2. Alternatively, you could run the following:

      git add .github/workflows/gh-pages.yml
git add .gitmodules
git add archetypes
git add config.toml
git add resources
git add themes

    3. Run git status to see if there any files that didn’t get added.

  2. Commit the added files to the repository:

    git commit -m "Initial commit of Hugo site."

    1. If git complains that you need to setup your user.name and user.email, follow the provided instructions.

  3. Next, setup the origin to point at the GitHub remote repository. If you haven’t initialized the GitHub repository with anything (as suggested above), GitHub will display instructions on how to do this. See About remote repositories on GitHub to learn about the URLs to use for different situations to connect to a repository.

    1. (RECOMMENDED) If you will use SSH on the terminal to interact with the repository, you can do the following:

      git remote add origin git@github.com:myusername/myusername.github.io.git

      Of course, myusername should be modified to fit your circumstances.

    2. (FOR REFERENCE ONLY) If you plan to use HTTPS to connect to the repository, you will use the following instead:

      git remote add origin https://github.com/myusername/myusername.github.io.git

      Notice the subtle differences in the URLs used. Again, see About remote repositories on GitHub to learn about the URLs to use for different situations to connect to a repository. For this tutorial, I recommend using the SSH approach and the related URL.

  4. Finally, you can push the repository to GitHub using the following command:

    git push -u origin main
    💡
    		 If you continued to use the master branch instead of main, then you should use git push -u origin master instead.

Configure GitHub Pages to Use the gh-pages Branch for Deployment

With all of this setup, we still need to configure GitHub Pages to use the gh-pages branch for deployment since that is the branch created by the GitHub scripting added in Setting Up the Repository for GitHub Actions.

To do this:

  1. Go to the main repository page on GitHub for the Hugo site repository.

  2. Under the Code and automation section on the left, select Pages.

  3. Under the Source option, you can use Deploy from a branch, the default as of this writing.

  4. Under the Branch option, select the gh-pages branch and hit the Save button in that section. The gh-pages branch should exist in the repository after the commits above since it is created by the gh-pages.yml automation. If it doesn’t you might need to look at the Actions area for the repository to see why the automation isn’t working.

At this point you should be able to go to https://myusername.github.io to get to your GitHub Pages site. Congratulations!

A full example of this technique can be found at https://github.com/pgrahamdev/pgrahamdev.github.io . The example site is hosted at https://pgrahamdev.github.io.

Useful Commands for Maintaining the Site

Once the site is up and running, the following commands can be useful for helping you maintain the site through Git and SSH:

  • git add <filename>: Before committing a file to your repository, you need to stage the change through running git add <filename> for each file you want to commit to the repository.

  • git commit -m "A commit message": Once the changes you want to make have been staged, then you can run git commit with a -m option to commit the changes with the given commit message. I recommend putting quotes around the commit message—​it may not work otherwise.

  • git push: Once you have committed the changes locally, you need to do a git push to push the changes to GitHub. This requires the setup for [SSH Configuration] to be in place.

  • hugo server: Before committing changes, it is always recommended to use hugo server in the top-level Hugo site directory to look at the site before pushing it to GitHub. This will catch issues early rather than looking to see what fails on GitHub itself.

Other Useful Hugo and Git References and Tips

  • Hugo Front Matter: Hugo uses "front matter" in Markdown and AsciiDoc files to provide Hugo information about a post or blog entry. See Content Management: Front Matter article for more information and examples.

  • Hugo Content Organization: See the Content Management: Content Organization article to better understand how to organize files for a site. Note that _index.md files can provide a while to style pages that list articles (index pages).

  • Hugo Menus: See the Content Management: Menus article for some useful information about creating menus for Hugo web sites.

  • Git Documentation: You can find useful Git documentation at Documentation section of the official Git web site. Specifically, there are a few references that are helpful: