DEV Community

loading...

Hugo Setup and Deployment

mikun
Another wanna be hacker. Always curious to learn how things work, especially in digital world.
Originally published at fahmifj.Medium on ・7 min read

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 cover the deployment/hosting steps too 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:

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 
Enter fullscreen mode Exit fullscreen mode

It should return something like this.

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

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
Enter fullscreen mode Exit fullscreen mode

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

C:\>move C:/path/to/your/hugo.exe C:/bin/
Enter fullscreen mode Exit fullscreen mode

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

rundll32.exe sysdm.cpl,EditEnvironmentVariables
Enter fullscreen mode Exit fullscreen mode

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.

Path variable

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

Adding a new path

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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...
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

$ cd my-blog 
$ hugo server
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

$ cd my-blog
$ git init
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

$ git submodule add https://github.com/adityatelange/hugo-PaperMod.git PaperMod
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Test it with:

$ hugo server
Enter fullscreen mode Exit fullscreen mode

04. Creating Your First Post

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

$ hugo new post/new-post.md
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/"
Enter fullscreen mode Exit fullscreen mode

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

baseURL: "https://fahmifj.github.io/my-blog/"
Enter fullscreen mode Exit fullscreen mode

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 | 0

Total in 147 ms
Enter fullscreen mode Exit fullscreen mode

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

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

Repository — my-blog

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

#!/bin/bash

echo -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"
fi

git commit -m "$msg"

# Deploy
git push -u origin main

# Go back to the root directory
cd ../
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 …

...<SNIP>..

Total 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>...
Enter fullscreen mode Exit fullscreen mode

If we check our repo it should be updated.

That’s how I deployed my blog at the first time.

But still, this is inefficient method because it wastes your bandwidth, thus in the next post, let’s employ GitHub action 😼.

In the meantime, try reading the following documentation:

Originally published at https://fahmifj.github.io on June 13, 2021.

Discussion (2)

Collapse
roneo profile image
Roneo.Org

Thanks for sharing! I love your clean theme BTW

Collapse
fahmifj profile image
mikun Author

You're welcome, I'm glad you liked it!