Hosting Hugo at GitHub Pages

Hugo is a framework written in Go, but no Go knowledge is necessary. All you need to do is choose a theme, install it with a Git command, change some configurations and start writing what you want using Markdown syntax. The hugo command transforms everything into pure HTML and CSS files you can host on GitHub Pages.

Step 1: Create a repository

Head over to GitHub and create a new public repository named username.github.io, where username is your username (or organization name) on GitHub.

If the first part of the repository doesn’t exactly match your username, it won’t work, so make sure to get it right. ¹

Step 2: Hello World

On your machine, create a new repository on the command line.

• I am using my username in the following examples. Change to yours.
• Maintain the gh-pages branch name. It will host the HTML and CSS files generated by Hugo, and ahead configurations will use its name.

mkdir delcastanher.github.io
cd delcastanher.github.io
git init
git checkout -b gh-pages
echo "Hello World" >> README.md
git add README.md
git commit -m "first commit"
git remote add origin git@github.com:delcastanher/delcastanher.github.io.git
git push -u origin gh-pages

Step 3: Create a new site

Let’s create the main branch, which will be the source code of our site. And you need Hugo installed.

git checkout -b main
hugo new site . --force

Step 4: Add a Theme

See themes.gohugo.io for a list of themes to consider. This quickstart uses the beautiful Ananke theme. ²

Download the theme from GitHub and add it to your site’s themes directory.

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

Step 5: Site configuration

Open up config.toml in a text editor and add the theme to the site configuration.

baseURL = "https://delcastanher.github.io/"
languageCode = "en-us"
title = "Delcastanher's Memory Allocation"
theme = "ananke"

Replace the title above with something more personal. Also, if you already have a domain ready, set the baseURL.

To test the site, run hugo server -D and navigate to http://localhost:1313/. To add some content, follow the Quick Start guide.

Step 6: Build Hugo With GitHub Action

GitHub executes your software development workflows. Everytime you push your code on the Github repository, Github Actions will build the site automatically. ³

Create a file in .github/workflows/gh-pages.yml containing the following content.

name: github pages

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'
          # 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

Step 7: Push it

Add, commit, and push your changes.

git add --all
git commit -m "Go Hugo"
git push -u origin main

Step 8: …and you’re done!

After executing push, go to the Actions tab on your GitHub repository and see the workflow and Hugo running. When it ends, fire up a browser and go to https://username.github.io.

Default Branch vs Page Branch

You will end up with two branches: main and gh-pages. The main branch is the only one that you will work on. The gh-pages branch is truncated every time you push at the main branch and populated with the static site generated.

Despite that, you will see that the gh-pages ended up being the Default branch. You can change this on the Settings tab on your GitHub repository, at the Branches submenu on the left. But to maintain everything working automatically, ensure that gh-pages is set as Source at the Pages submenu on the left.