Hugo Setup and Deployment

8 min readJun 13, 2021

Recently, I’ve been building my own blog at https://fahmifj.github.io/ and it has been up for three months now. To build it, I used a static site generator called Hugo. Hugo is a great tool for creating static websites in my opinion.

In this post, I’d like to share how to create your own and I’ll also cover the deployment/hosting steps using GitHub Pages!

Goals

Our main goals:

Installing Hugo
Using Hugo theme
Deploying Hugo site with Github

Prerequisites

And there are some prerequisites needed to accomplish these goals:

A GitHub account
Git Bash for Windows users
Basics knowledge of Git (commit, push, pull, creating repository, know what is local and remote repository)
Basics knowledge/use of CLI (cd, ls, pwd, mv, rm, mkdir)

If all set, then let’s get started!

01. Installing Hugo

First, download Hugo executable binary at:

https://github.com/gohugoio/hugo/releases

Pick your Hugo version according to what OS you’re on. There is also the extended version, which you should use if you’re building your own theme or picking a theme that uses Sass/SCSS.

From here, I don’t need to explain how to extract it, right?
I will just assume that you have downloaded the binary and extracted it somewhere on your system.

Let’s test it on terminal by typing.

$ hugo.exe

It should return something like this.

version hugo v0.82.0-9D960784+extended windows/amd64 BuildDate=2021-03-21T17:28:04Z VendorInfo=gohugoio

At this time, Hugo’s binary is not available in a system-wide (it’s not accessible outside the current directory).

So, let’s make it accessible from anywhere by adding the binary location to what is known as PATH variable.

01.1. Windows

For Windows users, let’s create a folder called bin in C:/ .

C:\>mkdir bin

Once the folder is created, move your Hugo binary into it.

C:\>move C:/path/to/your/hugo.exe C:/bin/

After that, hit Win + R on your keyboard and type:

rundll32.exe sysdm.cpl,EditEnvironmentVariables

You should see a window with “Environment Variables” in the title. We’re going to edit Path variable, so select that Path variable and click on Edit button.

On the Edit window, click on New button to add a new path and type C:\bin.

After that, just hit all the OK button.

Open your Windows terminal and run hugo version. If it returns the same output as previous one, then go to the section 02.

01.1. Linux

I know those who uses Linux probably already know how to 😁.

For Linux users, let’s create a folder called bin under /home/username/.local/[here].

$ mkdir -p ~/.local/bin

Open your .bashrc or .zshrc file, it is located at /home/username/.[zsh|bash]rc, with your favorite text editor such as vim (maybe?) then simply add these line at the top of your .bashrc/.zshrc

PATH_HUGO='/home/username/.local/bin'
export PATH=$PATH_HUGO:$PATH

Reopen your terminal and run hugo version from any directory and see if it's returns the version.

02. Creating Your First Site

We can create a site from anywhere by issuing the following command:

$ hugo new site [site-name]

I recommend you to create a site in a specific folder such as workspace.

For now, let’s create a site called my-blog.

$ hugo new site my-blog
Congratulations! Your new Hugo site is created in C:\Users\fahmi\Desktop\test\my-blog.
...<SNIP>d...

You can see that Hugo creates a new folder called my-blog at C:\Users\fahmi\Desktop\test\my-blog, and my-blog has the following directory structure:

my-blog
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Go to the my-blog folder and type hugo server in the terminal to host it locally.

$ cd my-blog 
$ hugo server

By default, the site is hosted at http://localhost:1313/ , but it's still empty because we haven't added any content yet.

03. Installing Hugo Theme

My blog uses a theme called PaperMod, so l’ll be using that too here.

First, let’s delete the previous my-blog and recreate it with the following command:

$ hugo new site my-blog -f yml

Let’s move into my-blog and initialize a git repository there.

$ cd my-blog
$ git init

After that, go to the themes folder and clone the PaperMod theme there.

$ cd themes 
$ git clone https://github.com/adityatelange/hugo-PaperMod PaperMod --depth=1

We’ll add the theme as a submodule of my-blog.

$ git submodule add https://github.com/adityatelange/hugo-PaperMod.git PaperMod

Now, let’s go back to the root directory ( my-blog), then replace/overwrite our config.yml with this, but change the value of baseUrl and theme to these:

baseURL: "" 
theme: PaperMod

Test it with:

$ hugo server

04. Creating Your First Post

We can create a new post with by issuing the following command:

$ hugo new post/new-post.md

You can edit new-post.md after that, the file should be under my-blog/content/post/[here].

$ ls -l my-blog/content/post/
total 1
-rw-r--r-- 1 Fahmi FJ 197121 70 Jun 13 09:34 my-post.md

To see your post in the site, change the value draft from true to false:

---
title: "My Post"
date: 2021-06-13T09:34:43+07:00
draft: false
---My first post

It should be on your site now.

05. Deploying Site on GitHub

From here, thing you need to know that when you run hugo server, Hugo will generate all the site resources and serve them from memory. But, if you run hugo, Hugo will generates all the site resources inside public folder (my-blog/public/[here]).

The files in this public folder are the files that we are going to host on GitHub. We can simply upload all the files in the public folder into a GitHub repository.

I’m not good at explaining it on English, so let’s do that in action!

But, before that, you have to change your site’s base URL in config.yml to:

baseURL: "https://[your_user_name].github.io/my-blog/"

For example, my username is fahmifj , so my config would be:

baseURL: "https://fahmifj.github.io/my-blog/"

Once you done with the config, type hugo at the site root directory, Hugo will re-generates the web files at the public folder.

$ hugo
Start building sites …| EN | FR | FA
-------------------+----+----+-----
  Pages            | 14 | 10 | 10
  Paginator pages  |  0 |  0 |  0
  Non-page files   |  0 |  0 |  0
  Static files     |  0 |  0 |  0
  Processed images |  0 |  0 |  0
  Aliases          |  3 |  0 |  1
  Sitemaps         |  2 |  1 |  1
  Cleaned          |  0 |  0 |  0Total in 147 ms

After that, create a new repository called my-blog on GitHub.

Once the repo is created, click on Upload an existing file.

Then simply drag and drop all the files from the public folder there.

Once all the files are uploaded, commit the changes, I’ll leave the commit message as default.

After that, go the GitHub pages settings at https://github.com/your-username/my-blog/settings/pages to host your site.

There you go!

If you don’t see your site there or it returns a 404 error, just wait for a few minutes more.

From here, we learned how to deploy/host our Hugo site on GitHub. However, this is not an efficient method of updating your site, therefore let’s write a deployment script.

06. Deployment Script

Assuming you’re inside my-blog , then go to the public directory, do files and folders clean up then initialize a git repository there.

$ cd public 
$ rm -rf * $ git init

Still inside the public directory, set the previously created my-blog repository as the remote repository and run git pull afterwards.

$ git remote add origin https://github.com/your-username/my-blog.git $ git pull origin main

Return to the site root directory then add the public folder as a submodule.

$ cd ../ 
$ git submodule add https://github.com/your-username/my-blog.git public

Now let’s create a deployment script at the site root directory and name it as deploy.sh:

#!/bin/bashecho -e "\033[0;32mDeploying blog to GitHub...\033[0m"# Clean public folder
hugo --cleanDestinationDir# Go to to public folder
cd public/# Add untracked files, hide output
git add -A > /dev/null# Generate a fixed commit message with date and time
msg="[`date "+%R %d-%h-%Y"]` Site update"
 
# Check for additional commit message
read -p "Add commit message: " add_msg
if [ "$add_msg" != "" ]
 then 
 msg="$msg - $add_msg"
figit commit -m "$msg"# Deploy
git push -u origin main# Go back to the root directory
cd ../

In Windows, even though it is a bash script, it will work with Git Bash.

Let’s test it by creating a new post.

$ hugo new post/second-post.md 
$ echo 'This is second post' >> content/post/second-post.md

Don’t forget to change the value of draft from true to false!

Now we can run the script, the output should looks something like this:

(my-blog)$ ./deploy.sh
Deploying blog to GitHub...
Start building sites …

                   | EN | FR | FA
-------------------+----+----+-----
  Pages            | 15 | 10 | 10
  Paginator pages  |  0 |  0 |  0
  Non-page files   |  0 |  0 |  0
  Static files     |  0 |  0 |  0
  Processed images |  0 |  0 |  0
  Aliases          |  3 |  0 |  1
  Sitemaps         |  2 |  1 |  1
  Cleaned          |  0 |  0 |  0Total in 155 ms
Add commit message:
[main af4c483] [11:00 13-Jun-2021] Site update
 9 files changed, 459 insertions(+), 8 deletions(-)
 create mode 100644 post/second-post/index.html
...<SNIP>...