這是一張有關標題為 Hugo 建站筆記 的圖片

Hugo 建站筆記

這是一篇建站筆記,詳細記錄如何一步一步透過 Hugo 實現建站的過程。

什麼是 Hugo

根據官網所描述,是一個基於 Go 語言所撰寫的快速且現代的靜態網站產生器(static site generator),其中靜態網頁(static web pages)的好處在於性能以及安全性是吸引人的主要原因。

透過 Hugo,會將撰寫的 Markdown 編碼成 HTML 頁面。由於 HTML頁面已經建構好,使用者在瀏覽時可以幾乎零延遲的載入。

其特點不需要後端程式或是資料庫(database)。也因為相較於非靜態網頁來得安全、漏洞更少。

動態網頁與靜態網頁

動態網頁(dynamic web page)是指當用戶訪問網頁時,其內容可以根據用戶的請求、操作,或其他特定條件而動態生成或更新的網頁。

伺服器端語言(server-side scripting)是實現動態網頁的重要技術,透過伺服器執行相關程式邏輯,生成對應的內容,並將結果回傳給用戶瀏覽器。

常見的伺服器端語言依熱門程度排序為:Node.js、PHP、Ruby on Rails、Go、Python、ASP.NET、JSP、CGI 等。

在過去撰寫部落格時,我曾使用過 WordPress 這個內容管理系統(Content Management System,CMS)。WordPress 是以 PHP 語言開發的,搭建 WordPress 需要有一台主機,主機可以是 Windows 或 Linux 系統,並設置在某個位置,例如雲端或本地環境,通常由主機服務商提供。完成設置後,需透過主機服務商提供的 FTP 或 SSH 配置進行連接。在主機上,需要安裝 Apache 或 Nginx 來處理 HTTP 請求,並安裝 PHP 執行 WordPress。同時,為了儲存文章內容,還需安裝 MySQL 或 MariaDB 資料庫。如果需要方便地管理資料庫,則可以選擇安裝圖形化管理工具,例如 phpMyAdmin(非必要)。

當 WordPress 安裝完成並正常運作後,通常會進行一系列操作,包括基本設定、SEO 優化、主題美化,以及部分外掛的安裝。目前,臺灣主流的旅遊網誌仍然普遍採用這套系統。終端使用者在瀏覽文章時,其動態網頁的基本運作流程為:

使用者透過瀏覽器發送 HTTP Request → Apache 處理請求並交給 PHP → PHP 查詢資料庫並生成 HTML → Apache 回傳 HTML 作為 HTTP Response 給使用者。

相較之下,靜態網頁僅需由 Apache 處理使用者的 Request 和 Response,無需依賴 PHP 或其他後端程式來動態生成內容。靜態網頁的特點在於快速、安全,且能即時將內容呈現給使用者,因為不需要等待後端程式執行完成。靜態網頁的基本運作流程為:

使用者發送 HTTP Request → Apache 傳送靜態 HTML → Apache 回傳 HTTP Response 給使用者。

兩者的差異在於伺服器端是否需要在使用者瀏覽時執行伺服器端的程式來生成內容。靜態網頁不需要伺服器端運行任何程式,也不依賴資料庫來存取文章。大多數文章內容在部署前已經被生成為單一的 HTML 檔案,直接提供給使用者,這使得靜態網頁更加快速且簡單。

建站流程

以下是建站的基本流程,可參考下圖的架構,並依序完成各步驟。後續將逐一講解每個步驟的細節,若需要更深入的內容,會在未來文章中補充說明:

  1. 開始與安裝
    安裝必要工具(例如 Hugo 和 Git)。

  2. 開始新的網站
    使用 Hugo 建立全新的網站專案。

  3. 初始化 Git Repo
    將專案初始化為 Git 儲存庫,方便版本控制。

  4. 安裝 Hugo 主題
    選擇並安裝適合的 Hugo 主題以美化網站外觀。

  5. 開始新的文章
    新增內容,例如部落格文章或頁面。

  6. 設定網站細節
    調整網站的設定檔(如 config.toml),包括網站標題、描述及其他參數。

  7. 執行 Hugo 伺服器
    本地啟動 Hugo 開發伺服器,預覽網站效果。

  8. 推送到遠端伺服器
    使用 Git 將網站專案推送至遠端儲存庫(如 GitHub)。

  9. 編譯並發佈網站
    使用 Hugo 將網站編譯為靜態檔案,並部署至主機或 CDN 上。

Flow chart to build Hugo sites

Flow chart to build Hugo sites

開始與安裝

在 Windows 與 Linux 上安裝 Hugo 非常簡單與快速,建議使用命令列的方式,可以更快速且一致性地完成操作。

另外,除了安裝 Hugo,Windows 用戶還需要額外安裝 Git,以實現原始檔案的版本管理。

未來在編輯文章時,若出現任何錯誤需要復原,都可以藉由 Git 快速進行回溯。

透過 Winget 安裝 Hugo (Windows)

1
winget install Hugo.Hugo.Extended

安裝結果:

Use winget to install Hugo

透過 snap 安裝 Hugo (Linux)

1
sudo snap install hugo

安裝結果:

wells@server:~$ sudo snap install hugo

[sudo] password for wells:

hugo 0.120.4 from Hugo Authors installed

透過 Homebrew 安裝 Hugo (macOS, Linux)

在使用 brew 指令前,需要先 安裝 Homebrew

1
brew install hugo

透過 Winget 安裝 Git (Windows)

預設 Linux 或 Mac 已經安裝好 Git 指令,故這裡只提及 Windows 上的安裝

1
winget install -e --id Git.Git

Use winget to install Git

檢查執行檔版本

安裝後可以檢查是否安裝成功,順便檢查版本號,目前安裝的 Hugo 版本為 v0.120.4,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

開始新的網站

在一個可以存放網誌原始檔的地方,Linux 可選擇個人的 Home 目錄(~/),Windows 可選擇使用者目錄(C:\Users\USER),想儲存在其他區域也是都可以的,要開始新的網站,輸入 hugo new site BLOG_NAME,並進入到該目錄即可,這邊以 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 # 列出目錄結構
archetypes  assets  content  data  hugo.toml  i18n  layouts  static  themes

如此一來就建立好了一個新的網誌,而這個網誌預設是沒有安裝主題與文章的,所以直接編譯的話是沒有內容的。

初始化 Git Repo

在進入到網誌目錄底下(~/my_blog),輸入 git init 便可以初始化本地的 local repo。後續可以 git status 查看 Untracked files。

預設 Git 是沒有追蹤任何檔案的,可以把 hugo.toml, archetypes 等相關檔案加入至索引對象(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

安裝 Hugo 主題

要安裝 Hguo 主題,我們可以先到 Hugo Themes 找一個喜歡的主題,主題的供應者會提供安裝的方式。

這裡以 PaperMod 主題為例子。並從 PaperMod - Installation 文件中可以得知安裝有不同方法。

Method 1 的話,則是在site 目錄下進行 git clone 即可。

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.

編輯 ~/my_blog/hugo.toml,並於後方新增一行 theme = ‘PaperMod’ 即可套用該主題,注意大小寫是有差異的。

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

開始新的文章

透過以下指令,便可新增一篇新文章

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

編輯 ~/my_blog/content/posts/my-first-post.md 就等同於在寫文章了,其中語法為 Markdown,記得把 draft = true 改為 false,確定此文章為 release 的狀態。

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

設定網站細節

在此階段,其實已經可以運行 Hugo Server 並看到網誌的效果。不過在執行伺服器前,可以考慮進行一些網站的基本設定,例如:

  1. 編輯 ~/my_blog/hugo.toml 的語言。
  2. 設定網誌名稱。
  3. 啟用或停用 emoji(enableEmoji)。
  4. 設定網站的 favicon。
  5. 添加網站摘要。
  6. 其他配置選項…

這些設定選項繁多,因此可以選擇在執行伺服器後再動態調整。

更多設定可參考官方文件:Configure Hugo。此外,您也可以根據習慣將 hugo.toml 轉換為 hugo.yaml

不同的 Hugo 主題可能需要特定的配置,這通常需要參考主題文件,並在對應的 config 文件中進行調整。

執行 Hugo 伺服器

根據官網描述,是一個高性能 Web 伺服器,不過更多來說是方便 Local 端的測試,可以透過以下指令來執行伺服器。

1
hugo server -D

其中 -D 也會建置 draft 的文章,最終建置預設是不會編譯 draft 文章。

 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

建立後,可以於瀏覽器中打開 http://localhost:46651,並看到部落格與文章。後續編輯配置或是修改文章都會看到即時的更新。

執行 Hugo Server

推送到遠端伺服器

安裝好主題、新增文章並編輯配置檔後,接下來要做的就是使用 Git 來管理目錄下的變更,並將這些變更推送到遠端伺服器進行管理與維護。

由於先前只執行了 git init,尚未設定遠端伺服器的連接。

假設您已在 GitHub 或其他伺服器上建立了對應的儲存庫(repo),接著會取得一段 SSH 連接方式,例如:

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

藉由 git remote add 與 git remote -v 可以新增與檢查當前本地端 repo 的 remote 狀態:

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)

確定本地端,修改的檔案都已經 git add 加入索引、並且 git push 加入預期的 commit 後,便可以 git push 把本地端的修改整個推送到遠端伺服器上。

編譯並發佈網站

編譯網站非常簡單,只要輸入指令 hugo 就會產出 ~/my_blog/public 目錄,該 public 裡面的 HTML 就可以放到伺服器上供他人預覽。網路上有提供數個免費靜態網頁的託管(hosting),像是:

  1. GitHub pages
  2. Cloudflare pages
  3. Netlify

其中目前使用的是 GitHub pages,支持自定義域名,可以整合 repo 與 GitHub Actions。

實現推送 repo 後,全自動編譯並 push 到 GitHub pages,在每個月 免費的額度 下其實是蠻充裕的。

結論

整個建立 Hugo 靜態網頁其實沒有很困難,就是安裝 Hugo 與 Git → 安裝主題 → 新增文章 → 發佈

中途 Git 引入是確保在修改網頁的過程中是能夠回朔的,如果真的不需要其實不用 git init,但也非常不建議。因為網頁突然不小心改壞了,要復原會有一定難度。

參考文獻

  1. Hugo - Quick start
  2. Benefits of static site generators
  3. Configure Hugo
  4. Hugo Themes
  5. PaperMod’s wiki
主題 Stack 由 Jimmy 設計