October 13, 2023

Hugo Workshop

A step-by-step guide on how to setup a HUGO website and publish it on Github pages

Creating the HUGO site

1
hugo new site <username>.github.io --format=yml

Setting up git and gh repo

First change dir to the newly created site dir with cd <username>.github.io. Now initialize git in the folder.

1
git init

Now we can add theme to our website as a submodule (yes, submodule as this give us power of clonig this repo with single command)

1
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

now we have to make sure that HUGO know that we want to use “PaperMod” theme.

1
echo "theme: \"PaperMod\"" >> hugo.yml

To test whether the theme is working or not… run the hugo server

1
hugo server -D

-D flag compiles the draft pages also (helpful when writing actual blogs). If all works correctly then you should be able to see first web page on localhost:1313

adding these changes and then commiting it.

1
git add .
2
git commit -m '<initial commit>'

Now we have to setup the GitHub repo so our web pages are hosted using GitHub pages. So we have to create our repo with the following command,

1
gh repo create <username>.github.io --public --push --source=. --remote=origin

now we will see meaning of each flag,

--public : this creates a public repo.
--push : push the local commits to the created repo.
--source : and the push specified directory as the source.
--remote=origin : this names the remote as origin.

Since, this pushes the commit as well so essentially your github repo should contain HUGO files. initial commit

Customizing your metadata

Since this is our personal blogging site so we should have good landing page with showing who you are with some social media. For example, we have a defined page in our theme (see Fig).

Your current hugo.yml file should look like this,

1
baseURL: https://example.org/
2
languageCode: en-us
3
title: My New Hugo Site
4
theme: "PaperMod"

Here, we start with baseURL change it to https://<username>.github.io/ and title to whatever you want.

Now, actually at this stage this is your choice what you want to do with your website. But the following setting and options are recommended but you can definitely change them. So in the end it should look like…

1
baseURL: "https://anayRetard.github.io/"
2
languageCode: en-us
3
title: The Retard
4
theme: "PaperMod"
5
enableEmoji: true
6
author: "Anay Kuljeet"
7

8
mainSections:
9
  - blog
10
  - archives
11

12
menu:
13
  main:
14
    - name: Home
15
      pageRef: /
16
      weight: 10
17
    - name: Blogs
18
      pageRef: /blog
19
      weight: 20
20
    - name: Archives
21
      url: /archives
22
      weight: 30
23

24
params:
25
  profileMode:
26
    enabled: true
27
    title: "I'm Retarded" ## optional default will be site title
28
    subtitle: "Test Website by Slashdot."
29
    author: "hehe"
30
    imageUrl: "/images/profileImg.jpg" ## optional
31
    imageTitle: "Profile Image" ## optional
32
    imageWidth: 400 ## custom size
33
    imageHeight: 300 ## custom size
34
    buttons:
35
      - name: Blogs
36
        url: "/blog"
37

38
  socialIcons:
39
    - name: "Linkedin"
40
      url: "https://slashdot-iiserk.github.io"
41
    - name: "YouTube"
42
      url: "https://www.youtube.com/@piyushkrsingh"
43
    - name: "Github"
44
      url: "https://github.com/iamPiyushKrSingh"
45
    - name: "Instagram"
46
      url: "<>"

Now, our main landing page is ready. But put your profile pic in static/images/profileImg.jpg.

Creating sections

Create /archives with the following command,

1
hugo new archives.md

and change metadata of this file as

1
---
2
title: "Archives"
3
layout: "archives"
4
url: "/archives/"
5
summary: archives
6
---

Adding first blog

Let’s say you are gonna record today’s experience. So let’s create our first blog,

1
hugo new blog/HUGO-workshop-experience.md

open the file content/blog/HUGO-workshop-experience.md, metadata will look like,

1
+++
2
title = 'HUGO Workshop Experience'
3
date = 2023-10-14T02:53:32+05:30
4
draft = true
5
+++

Then add the content after the data. Now, lets test the blog with,

1
hugo server -D

After completing blog change as draft = false.

Setup GitHub Actions

First enable read-write perms for workflow action from setting, by going into Settings -> Action -> General -> Workflow Permissions.

Let’s first create action yml file but command

1
mkdir -p .github/workflows && touch $_/hugo.yml

After creating this file, add the following thing in the file directly,

1
name: Deploy Hugo site to Pages
2

3
on:
4
  push:
5
    branches:
6
      - main ## Set a branch to deploy
7
  pull_request:
8
    branches:
9
      - main
10

11
permissions:
12
  contents: write
13
  pages: write
14
  id-token: write
15

16
concurrency:
17
  group: "pages"
18
  cancel-in-progress: false
19

20
## Default to bash
21
defaults:
22
  run:
23
    shell: bash
24

25
jobs:
26
  build-and-deploy-site:
27
    runs-on: ubuntu-latest
28
    steps:
29
      - name: Checkout repo
30
        uses: actions/checkout@v3
31
        with:
32
          submodules: true
33
          fetch-depth: 0
34

35
      - name: Setup Hugo
36
        uses: peaceiris/actions-hugo@v2
37
        with:
38
          hugo-version: "latest"
39

40
      - name: Build site with HUGO
41
        run: hugo --minify
42

43
      - name: Deploy to GitHub Pages
44
        uses: peaceiris/actions-gh-pages@v3
45
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
46
        with:
47
          github_token: ${{ secrets.GITHUB_TOKEN }}
48
          publish_dir: ./public

Now, we can push the changes to see the magic of GitHub Actions, with

1
git add .
2
git commit -m "first blog"
3
git push origin main

Now chnage the deployment branch to gh-pages. In settings of the repo under pages, select the deployment brach as gh-pages as gh-pages-settings

Adding New Content

To add content we will add soon.