This tutorial is to teach you how to make youre own hugo-generated static site served by Github Pages, within a single repo.

Prerequisites

  1. Github & CircleCI account
  2. Newly-generated SSH key pair for safety reasons(see here)
  3. Hugo installed locally

Dive in

Generate site source with hugo command:

hugo new site <SITE_NAME>

Create a repo for your site: <SITE_NAME>.github.io(Be aware: this tutorial uses User/Organization Pages rather than Project Pages, see here), clone it, and create a new branch called source(whatever you like):

git clone https://github.com/<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git
cd <SITE_NAME>.github.io
git checkout -b source

Copy everything from the folder created by hugo above into repo:

mv ../<SITE_NAME>/* .

Go to circleci.com and add your .github.io project. Goto Project Settings, under SSH Permissions, add SSH private key you just generated(see here), copy the Fingerprint for use below.

Go to Github your project settings, under Deploy Key, add SSH public key you just generated.

Create config file for CircleCI:

mkdir .circleci
cd .circleci
touch config.yml

config.yml(Edit it with your own information):

version: 2.0

jobs:
    build:
        docker:
            - image: felicianotech/docker-hugo:latest
        working_directory: ~/<SITE_NAME>.github.io
        steps:
            - add_ssh_keys:
                fingerprints:
                    - "<FINGERPRINT_YOU_JUST_COPIED"
            - checkout
            - run:
                name: Get current site
                working_directory: ~/
                command: git clone -b master [email protected]:<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git public
            - run:
                name: Generate site
                working_directory: ~/<SITE_NAME>.github.io
                command: HUGO_ENV=production hugo -d ~/public
            - deploy:
                name: Deploy to Github Pages
                working_directory: ~/public
                command: |
                    git config credential.helper 'cache --timeout=120'
                    git config user.email "<YOUR_EMAIL>"
                    git config user.name "Deployment Bot"
                    git add .
                    git commit --allow-empty -m "Trigger deployment"
                    git push -q [email protected]:<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git master

workflows:
  version: 2
  main:
    jobs:
    - build:
        filters:
          branches:
            only: source

Now push your files to Github:

git add .
git commit -m "first commit"
git push origin source

For every time you push to the source branch, CircleCI will always trigger a hugo generation to the master branch, where the site’s static file generated by Hugo is placed.

Wait for CircleCI’s job done, then visit <SITE_NAME>.github.io and enjoy!