Hugo Site Building Notes

What is Hugo

According to the official website, Hugo is a fast and modern static site generator written in Go. The advantages of static web pages include performance and security, which are the main attractions.

With Hugo, Markdown content is encoded into HTML pages. Since the HTML pages are pre-built, users can load them with almost zero latency.

A key feature is that Hugo does not require backend programming or a database. This makes it more secure and less vulnerable compared to non-static web pages.

Dynamic vs Static Web Pages

Dynamic web pages change content based on user requests, actions, or other conditions at the time of the visit.

Using server-side scripting languages, the server executes the relevant programs and then returns the results to the user.

Common languages in order of popularity: Node.js, PHP, Ruby on Rails, Go, Python, ASP.NET, JSP, CGI, etc…

In the past, I used WordPress, a content management system (CMS) developed in PHP, to write blogs. Setting up WordPress requires a host, either Windows or Linux, usually provided by a hosting provider, and involves obtaining FTP or SSH configurations. After setting up the host, Apache or Nginx is installed to handle HTTP requests, along with PHP for running WordPress. For storing posts, MySQL or MariaDB databases are needed, and phpMyAdmin can be installed for database management if necessary.

Once WordPress is running, settings, SEO optimization, theme customization, and plugin installations are performed. Most mainstream travel blogs in Taiwan still use this system. The dynamic web page process is as follows:

User sends Request → Apache → PHP → Database → HTML → Apache → Response to User

In contrast, static web pages only require Apache to handle the user’s Request and Response, without PHP processing. The main advantages are speed and security, as there is no need to wait for backend processing. The static web page process is:

User sends Request → Apache → HTML → Apache → Response to User

The difference lies in whether server-side programs are executed to render the page. Static web pages do not require database access as most content is pre-compiled into single HTML files.

Site Building Process

The site-building process can be summarized in the following steps, which will be detailed further in subsequent sections:

Start and Install (Hugo, Git)
Start a New Site
Initialize Git Repo
Install a Hugo Theme
Create New Content
Configure Site Details
Run Hugo Server
Push to Remote Server
Build and Deploy the Site

Start and Install

Installing Hugo on Windows and Linux is quick and easy, recommended via command line for consistency.

Besides Hugo, Windows users need to install Git for source file management.

Future article edits can be quickly reverted using Git.

Install Hugo via Winget (Windows)

1
winget install Hugo.Hugo.Extended

Result:

Use winget to install Hugo

Install Hugo via Snap (Linux)

1
sudo snap install hugo

Result:

wells@server:~$ sudo snap install hugo

[sudo] password for wells:

hugo 0.120.4 from Hugo Authors installed

Install Hugo via Homebrew (macOS, Linux)

Before using brew, install Homebrew

1
brew install hugo

Install Git via Winget (Windows)

Assuming Git is pre-installed on Linux or Mac, here is the Windows installation:

1
winget install -e --id Git.Git

Use winget to install Git

Check Executable Versions

Verify successful installation and check versions. Currently installed versions are Hugo v0.120.4 and Git v2.43.0

1
2
3
4
5
wells@server:~/wellwells_hugo$ hugo version
hugo v0.120.4-f11bca5fec2ebb3a02727fb2a5cfb08da96fd9df+extended linux/amd64 BuildDate=2023-11-08T11:18:07Z VendorInfo=snap:0.120.4

wells@server:~/wellwells_hugo$ git --version
git version 2.43.0

Start a New Site

In a directory where you want to store your blog source files, choose your Home directory (~/) on Linux or the User directory (C:\Users\USER) on Windows. You can also choose other locations as desired. To start a new site, enter hugo new site BLOG_NAME and navigate into the directory. Here is an example using my_blog:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
wells@server:~$ hugo new site my_blog
Congratulations! Your new Hugo site was created in /home/wells/my_blog.

Just a few more steps...

1. Change the current directory to /home/wells/my_blog.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

wells@server:~$ cd my_blog/
wells@server:~/my_blog$ ls # List directory structure
archetypes  assets  content  data  hugo.toml  i18n  layouts  static  themes

A new blog site is created, which by default has no theme or content. Direct compilation will result in an empty site.

Initialize Git Repo

Navigate to the blog directory (~/my_blog) and initialize a local Git repo with git init. Use git status to check Untracked files.

By default, Git does not track any files. Add hugo.toml, archetypes, and other relevant files to the index (git add).

 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
36
37
38
39
wells@server:~/my_blog$ git init
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint: 
hint:   git config --global init.defaultBranch <name>
hint: 
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint: 
hint:   git branch -m <name>
Initialized empty Git repository in /home/wells/my_blog/.git/
wells@server:~/my_blog$ git status
On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .hugo_build.lock
        archetypes/
        hugo.toml

nothing added to commit but untracked files present (use "git add" to track)

wells@server:~/my_blog$ git add archetypes/ hugo.toml
wells@server:~/my_blog$ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   archetypes/default.md
        new file:   hugo.toml

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .hugo_build.lock

Install Hugo Theme

To install a Hugo theme, visit Hugo Themes and choose a theme. Theme providers usually provide installation instructions.

Using PaperMod as an example, follow the PaperMod - Installation guide. Method 1 involves git cloning in the site directory.

1
2
3
4
5
6
7
8
wells@server:~/my_blog$ git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
Cloning into 'themes/PaperMod'...
remote: Enumerating objects: 134, done.
remote: Counting objects: 100% (134/134), done.
remote: Compressing objects: 100% (113/113), done.
remote: Total 134 (delta 33), reused 57 (delta 15), pack-reused 0
Receiving objects: 100% (134/134), 263.32 KiB | 1.61 MiB/s, done.
Resolving deltas: 100% (33/33), done.

Edit ~/my_blog/hugo.toml and add the following line at the end to apply the theme. Note that the case is important:

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

Start a New Article

With the following command, you can create a new article:

1
2
wells@server:~/my_blog$ hugo new content posts/my-first-post.md
Content "/home/wells/my_blog/content/posts/my-first-post.md" created

Editing ~/my_blog/content/posts/my-first-post.md is equivalent to writing an article. The syntax used is Markdown. Remember to change draft = true to draft = false to ensure that the article is in the release state.

my-first-post.md

1
2
3
4
5
6
7
8
+++
title = 'My First Post'
date = 2023-11-27T10:58:32+08:00
draft = false
+++

Hello, My Site
I'm Wells

Website Configuration

At this stage, you can actually run the Hugo server and view your blog. However, before running the server, you might want to consider configuring some blog details, such as:

Editing the language in ~/my_blog/hugo.toml
Blog title
Whether to enable emojis (enableEmoji)
The website’s favicon
Summary
Other configurations…

Due to the extensive settings available, you can also dynamically adjust them after running the server.

For more configuration options, refer to Configure Hugo. At this point, you might also consider converting hugo.toml to hugo.yaml if you prefer.

Additionally, different themes have theme-specific configurations, usually specified in the theme’s config settings.

Running the Hugo Server

According to the official website, Hugo is a high-performance web server, though it is mainly convenient for local testing. You can run the server with the following command:

1
hugo server -D

Including the -D flag will also build draft articles. By default, the final build will not compile draft articles.

 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
wells@server:~/my_blog$ hugo server -D
port 1313 already in use, attempting to use an available port
Watching for changes in /home/wells/my_blog/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /home/wells/my_blog/hugo.yaml
Start building sites … 
hugo v0.120.4-f11bca5fec2ebb3a02727fb2a5cfb08da96fd9df+extended linux/amd64 BuildDate=2023-11-08T11:18:07Z VendorInfo=snap:0.120.4


                   | ZH-TW  
-------------------+--------
  Pages            |    10  
  Paginator pages  |     0  
  Non-page files   |     0  
  Static files     |     0  
  Processed images |     0  
  Aliases          |     2  
  Sitemaps         |     1  
  Cleaned          |     0  

Built in 25 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:46651/ (bind address 127.0.0.1) 
Press Ctrl+C to stop

After starting the server, you can open http://localhost:46651 in your browser to view the blog and articles. Any subsequent edits to the configuration or modifications to the articles will be updated in real-time.

Running the Hugo Server

Pushing to a Remote Server

Once the theme is installed, articles are added, and configuration files are edited, the next step is to manage the changes in the directory using git and push them to a remote server for management and maintenance.

Since we previously only performed git init without adding a remote server, let’s assume that a GitHub repository has already been created, or another server is ready with the repository. You will eventually obtain an SSH connection string:

1
git@github.com:USER/private.repo.git

You can add and check the current local repository’s remote status using git remote add and git remote -v:

1
2
3
4
wells@server:~/my_blog$ git remote add main git@github.com:USER/private.repo.git
wells@server:~/my_blog$ git remote -v
main    git@github.com:USER/private.repo.git (fetch)
main    git@github.com:USER/private.repo.git (push)

Ensure that all modified files have been added to the index using git add, and that the changes are committed using git commit. Once this is done, you can push the local changes to the remote server using git push.

Building and Publishing the Website

Building the website is straightforward. Simply enter the command hugo, and it will generate the ~/my_blog/public directory. The HTML files within this public directory can be uploaded to a server for others to view. There are several free static site hosting services available online, such as:

Among these, we are currently using GitHub Pages, which supports custom domains and integrates with repositories and GitHub Actions.

This setup allows for automatic building and pushing to GitHub Pages after each repository push. The free monthly quota is quite sufficient for most users.

Conclusion

Creating a Hugo static website is not particularly difficult. The steps are straightforward: install Hugo and Git → install a theme → add articles → publish.

Introducing Git into the process ensures that you can track and revert changes made to the website. While it’s technically possible to skip git init, it is highly discouraged. Reverting changes manually can be quite challenging if the website gets accidentally broken.