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!
Our main goals:
- Installing Hugo
- Using Hugo theme
- Deploying Hugo site with Github
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!
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.
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.
For Windows users, let’s create a folder called bin in C:/ .
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:
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.
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
.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
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.
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.
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
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.
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:
For example, my username is fahmifj , so my config would be:
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
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.
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/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 ../
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 … ...<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>...
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.