Hugo is blazing fast framwork to build websites. Recently, I migrated my blog from ghost+ghost-buster to hugo and gh pages.

I am assuming that you have git and hugo installed on your machine.

Setting up git repositories -

Github has two types of pages : 
    - User or Organization pages - 
    (e.g. https://<USERNAME|ORGANIZATION>.github.io)
    - Project pages -
    (e.g. https://<USERNAME|ORGANIZATION>.github.io/<PROJECT-NAME>)

Refer github pages documentation for more information.

• Create a <hugo-blog> git repository which will contain Hugo website.
• Create a <https://<USERNAME>.github.io> git repository. This repository will contain content generated by hugo framework.
• Open command line and create new hugo site by running hugo new site <your-site-name>
• Clone your <hugo-blog> respository by running git clone <REPOSITORY-URL>
• Paste all content from <your-site-name> folder to <hugo-blog> directory
• Now, you have brand new hugo website ready, you will need change config.toml file accordigly. Excerpt of example config.toml :

# Full example at https://github.com/geekwhocodes/hugo-ink/blob/master/exampleSite/config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "Ink"
theme = "ink"
paginate = 5
copyright = "© Copyright notice"

Adding theme from Hugo Themes -

• You can copy and paste theme in themes folder or you can add git submodule
• Adding theme as a git submodule - find your choice of theme (e.g. https://github.com/knadh/hugo-ink)

# 1. Run 
bash git submodule add https://github.com/knadh/hugo-ink themes/hugo-ink
# 2. git submodule init
# 3. git submodule update

# Refer https://git-scm.com/book/en/v2/Git-Tools-Submodules for more infomation on submodules

• After running above commands, git will automatically clone theme inside themes folder
• To run website locally, execute hugo server or hugo server -t <THEME-NAME> and make sure everything works on your machine.

Adding Github Action Workflow -

Github actions makes it easy to build, test and deploy your code right from github. It has plenty of actions available to talk to third party platforms. If you want something custom, you can build your own actions.

• Create .github folder in your <hugo-blog> directory and then create workflows folder under that.
• Create gh-pages.yml file under workflows folder, your ``` directory will look something like this:
• Github workflow yml, paste this code into gh-pages.yml file -

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

name: Deploy
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with: 
          submodules: true
          fetch-depth: 0 #Fetch all history 
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.68.3'
      - name: Hugo Build
        run: hugo --minify
      - name: Copy README & LICENSE
        run: |
          cp -f ./README.md ./public/README.md
          cp -f ./LICENSE ./public/LICENSE
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.HugoBlogToken }}
          external_repository: "USERNAME/USERNAME.github.io"
          publish_branch: master
          publish_dir: ./public
          cname: ""
          commit_message: ${{ github.event.head_commit.message }}
          user_name: 'Github Actions'
          user_email: 'github-actions[bot]@users.noreply.github.com'

• line 25 Deploy step will push content generated by hugo framework in ./public folder to your <https://<USERNAME>.github.io> repository, to do this you will need two things

  • Personal Access Token
    • Go to Tokens
    • Generate new token, select repo scope and add appropriate note (e.g. hugo-blog access token). Copy that token and save it for later
  • Configure Secret in <<hugo-blog>> repository -
    • Go to your <<hugo-blog>> repository -> settings -> secrets -> click on ```Add a new secret
    • Give secret this name - HugoBlogToken and paste Personal Access Token generated from previous step

• line 32 You can configure custom domain for your website. Read more information

• Now, everything is in place. Push your changes to remote <<hugo-blog>> repository. Github Actions will execute gh-pages.yml workflow and publish your website to <<USERNAME/USERNAME.github.io>> repository.

• Your brand new website will be avaiable at https://<<USERNAME>>.github.io

If you need help, reach me on twitter @_ganesh_raskar

Keep learning!