Hugo Setup

Oct 13, 2021 · 5 min read · Hugo  ·
Share on:

Welcome to andrewfitzy.github.io, this first post will give a step by step guide of how I got this site up and running.

Many of the steps have been copied from other sites, however I didn’t find an easy to follow guide to getting my setup in place, shout out to the following places though for inspiration:

Create a git repos for the site source and clone

<account_name>.github.io

Each GitHub account can have a public <account_name>.github.io repository associated with it, these are referred to a GitHub pages. GitHub pages are hosted sites where you can host almost anything as long as it doesn’t break the GitHub pages rules. This repo will be our target repo where the Hugo source is built to.

Hugo site source

Using GitHub create a new repo to store the source code for the Hugo site. This can be a private repo, we will be building and publishing from this repo to the <account_name>.github.io repo.

Once the repo is created, clone it.

Create a Hugo site

Using a terminal, navigate to the parent directory of the git repo we’ve just cloned. Initialise the Hugo site in the cloned private repo. My repo is called site-source so replace this with whatever the name of your private repo is.

hugo new site --force site-source

Add a theme to the Hugo site, there are plenty to choose from at themes.gohub.io but I used the Ananke theme as this is the one used in the Quckstart guide

cd site-source
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Finally use the theme by updating the site configuration:

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

Now you should be able to start the Hugo server and see an empty site if you navigate to http://localhost:1313/. To start the server:

hugo server

Create secrets and add to GitHub

When we create our GitHub actions file, we will use actions-gh-pages to publish from one repo to another and we will set this up to happen via deployment keys. So, first step is to set up public/private keys for deployment:

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

This will result in the creatio of 2 files in the ~/.ssh directory.

In the GitHub console:

  1. Click setting for the GitHub pages site (this is our <account_name>.github.io repo)
  2. Click Deploy keys
  3. Create a new deploy key called ACTIONS_DEPLOY_KEY.pub and copy in the contents of the ~/.ssh/gh-pages.pub file.
  4. Click setting for the source site (in my case it’s the site-source private repo)
  5. Click Secrets
  6. Create a new secret key called ACTIONS_DEPLOY_KEY and copy in the contents of the ~/.ssh/gh-pages file.

GitHub is now set up such that an action running in the site-source repo can publish to the GitHub pages repo.

Create the GitHub actions file

This is the final step to setting up our build pipeline. In the source repo (site-source in my case) create a folder called .github, within this create a folder called workflows and within this folder create a file called gh-pages.yml. Finally populate this file with this content:

name: site-source

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        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'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./public
          external_repository: andrewfitzy/andrewfitzy.github.io
          publish_branch: master # The branch of the external_repository to publish to

Much of the above configuration is discussed on the actions-gh-pages and the Host on GitHub pages of the Hugo site. I found that I had to provide external_repository and publish_branch to get my pipeline building and deploying automatically so that pushing an update to my source repo results in a post appearing on http://andrewfitzy.github.io.

Assuming this guide has been followed and all has worked out ok, navigating to your GitHub pages site should result in a site that looks like…
Default Hugo page

Create a new post (like this one) and watch the magic

Now that we have our site set up, each time we want to add some content we can use the following command:

hugo new posts/<title-of-post>.md

Where <title-of-post> is the, err, title of the post. In this case I called this post hugo-setup. This command will result in a markdown file which can be edited with the content of the post. By default, the post will be created as a draft post, this means that it can be checked in but will not be published automatically.

To see what the draft post would look like, a local Hugo server can be started with the option to view draft posts turned on:

hugo server -D

Any changes to the draft post that are saved will be recompiled and can be viewed immediately in the browser. Once you’re happy, change draft to false in the header, commit and push to GitHub and that’s it, the site will be rebuilt and published.

Thankyou for making it this far, I hope that the information has been useful.