選用技術特性

  • 使用近年很流行的「Static Site Generator」(靜態網站產生器)方式架站。有以下特點:
    1. 因為內容都是靜態產生,不需要後端處理,加上使用快取會比動態產生的網頁更有效率,請求速度很快。
    2. 不需要架設資料庫。
    3. 理論上比任何動態網站更安全。

目前主流的三大靜態網站產生器

  1. Jekyll
    由 Github 聯合創始人 Thomas Preston-Werner 使用 Ruby 語言所開發。

  2. Hexo
    由台灣人 陳嘉輝(Tommy Chen) 使用 JavaScript on Node.js 所開發。

  3. Hugo
    由 Steve Francia 原創,自 v0.14 (2015年) 由 Bjørn Erik Pedersen 主力開發,使用 Go 語言的開放原始碼專案。

更進一步的比較文章已經很多大大分享,可以先參考以下這篇說明(如何正確選擇靜態網站產生器:Jekyll vs. Hugo vs. Hexo):
How to Choose the Right Static Generator: Jekyll vs. Hugo vs. Hexo

本篇文章會著重在我選擇使用「Hugo」的觀點上,
不過有些功能還尚未深入使用,如果有其他發現或有想要補充的會再更新本文。


Hugo 優點

  1. 建構速度目前比其他主流產生器快。
  2. 使用 Go 語言編寫,重點是使用編譯完成的 binary ,不需要額外安裝對應的語言環境。
  3. 免費開源且國內外資源多。

Hugo 缺點

  1. 可擴展的外掛比較少(但內建功能已很多)。
  2. 沒有內建佈景風格(需要選一個第三方設計好的佈景安裝)。
  3. 需要了解一些 Go 語言的使用方法(對想學習或已經熟悉的人來說不算缺點)。

最後因為 Go 程式語言本來就在我的學習清單內,加上它瑕不掩瑜的速度優勢,Hugo 就從中脫穎而出了。
台灣之光 Hexo 不好意思了!


Hugo 簡易起手式

佈景主題風格

  如果還沒看過任何 Hugo 佈景風格的話,建議可以先看一下有沒有自己喜歡的佈景,這是其中一個管道:
Hugo Themes

  會建議沒有看過的人先看一下佈景範例的原因是:「網站最終得要是自己喜歡的樣子」

  雖然聽起來是廢話吼,但真的找不到喜歡的佈景,這個時候跳槽到 Hexo 也不會太遲XD(Hexo 也很多好看的佈景風格,舉例:hexo-theme-butterfly)。

  如果一開始就有自己喜歡的佈景,有程式碼能參考、有人持續維護,自己改起來也比較省力,前一章那些優缺點都只是開發過程中會遇到的問題,網站是不是自己要的模樣,會是在這過程中最大的動力源,往後花最多時間的往往都是在調整佈景樣式(當然如果你是技術能力高超,調教信手沾來的不在此限XD)。

  當然佈景效果越複雜的,調整設定上要注意的事情也會比較多,這就看使用者的需求取捨了。如果是對架站比較陌生的朋友,建議可以先從看起來單純乾淨的佈景開始玩,比較清楚後再套用其他佈景測試,Hugo 很多預設參數都是佈景間共用的,初期轉換佈景的成本不會很大。

編輯工具

  本篇使用的都是微軟出品的 Visual Studio Code(簡稱 VS Code)作為架站和撰文用的 IDE。去年 2021 年統計,使用頻率最高的開發工具便是佔 71.06% 的 VS Code;很多前端、Go Lang 工程師也都是使用此款 IDE,這邊就不再多做介紹了。

這邊提供一下官方下載點:
Visual Studio Code - Code Editing. Redefined

Hugo 推薦 VS Code 外掛

  … 有想到其他的再補充

版本控制工具

  這邊建議使用 Git 作為該專案版本控制工具。

  Hugo 大多文件都會提到使用 Git 去安裝佈景主題,部屬到 Github Pages 網頁代管服務也是必須使用到 Git;如果目前環境上沒有,建議可以先安裝起來。

因為 Git 也算是當代必學的版控工具了,本篇就不多做闡述,詳細安裝、使用方法可以參考:
Git 安裝教學


安裝 Hugo CLI

  以下範例會預設安裝「Hugo extended」(擴展版本),好處是內建了許多配置工具,像是自動轉譯 SASS/SCSS 的功能;套用佈景時比較不容易遇到錯誤。

Linux

如果尚未安裝套件管理工具「Snap」的話,可以參考 Linux 技術手札 此篇文章 安裝。

確認 Snap 是否有安裝,可以執行以下指令看是否能查到版本號:

1snap version

透過 Snap 安裝 Hugo:

1sudo snap install hugo

透過 Snap 更新 Hugo:

1sudo snap upgrade hugo
2sudo snap upgrade hugo-extended --force

macOS

如果尚未安裝套件管理工具「Homebrew」的話,可以參考 此連結 安裝。

確認 Homebrew 是否有安裝,可以執行以下指令看是否能查到版本號:

1brew -v

透過 Homebrew 安裝 Hugo:

1brew install hugo

透過 Homebrew 更新 Hugo:

1brew upgrade hugo
2brew upgrade hugo-extended --force

Windows

如果尚未安裝套件管理工具「Chocolatey」的話,可以參考 此連結 安裝。

確認 Chocolatey 是否有安裝,可以執行以下指令看是否能查到版本號:

1choco -v

透過 Chocolatey 安裝 Hugo:

1choco install hugo-extended -confirm

透過 Chocolatey 更新 Hugo:

1choco upgrade hugo
2choco upgrade hugo-extended --force

Hugo 安裝完測試

輸入以下指令檢視 Hugo 版本號:

1hugo version

↑ 有出現 hugo v... 開頭的訊息便表示成功安裝了!


建立一個 Hugo 專案

安裝完上述環境後,便可以透過以下指令建置新的 Hugo 專案:

1hugo new site [project name]
2
3# [project name] 可以替換成你想要的專案名稱

↑ 執行指令後,會在指定目錄下產生 Hugo 網站的結構目錄

輸入指令進到該專案目錄底下

1cd [project name]

試著執行看看 Hugo 專案

1hugo server

↑ 點開產生出的 localhost 網址,會發現網頁只有「Page Not Found」的訊息,代表站台雖然能執行但沒有佈景也沒有內容,目前還是空殼的狀態。

按下 Ctrl+C 關閉執行中的專案站台。

使用佈景主題

一開始看上的佈景主題這時可以開始套用了。

雖然每個佈景的安裝說明不盡相同,但大多都會採用「Git Submodule」的方式安裝,以下擷取自「Hugo Profile」佈景的 安裝文件 供參考:

1# 必須先初始化 Git
2git init
3
4# 透過 Git 將佈景主題 submodule 到 Hugo 專案內
5git submodule add https://github.com/gurusabarish/hugo-profile.git themes/hugo-profile

接著到 Hugo 專案主目錄底下的「config.toml」啟用佈景:

1baseURL = 'http://example.org/'
2languageCode = 'en-us'
3title = 'My New Hugo Site'
4
5# 新增底下這行,佈景名稱需對應 themes/ 路徑底下的佈景目錄名稱
6theme = "hugo-profile"

剩下補上一些細部設定,開啟 home 連結和 post 連結:

1[params]
2  title = "Hugo Profile"
3  description = "Text about my cool site"
4
5[[menu.main]]
6  name = "Blog posts"
7  weight = 1
8  url  = "posts/"

關於「Hugo Profile」佈景的其他設定項目,可以參考文件

補充

Hugo 可支援的 config 風格不止一種,會發現每個佈景文件使用的目錄分類方式、格式或參數名稱都不盡相同,文檔格式就支援 toml、yaml、json 三種格式且皆可互換,可以適當的調整成自己習慣的風格,在參考各佈景的設定方法時還請注意一下。

建立第一篇文章

為了在站台執行後能有文章顯示,可以執行以下指令建立文章:

1hugo new posts/first-post.md


↑ 指令執行完會自動在指定路徑的目錄內建立文章範本。

--- 之上的是文章的設定參數,包含標題、時間、分類、標籤、是否為草稿… 等等,也請參考各自佈景文件說明。

下半部份則是文本內容,
預設使用的標記式語言是 Markdown,著名的線上協作筆記 HackMD 就是採用該標記語言去撰文,有熱心網友整理了實用的 Markdown 語法大全

我們先簡單的寫一下文章內容貼進 .md 檔內:

 1# Blog 測試
 2
 3## h2
 4
 51. 一一一
 62. 二二二
 73. 三三三
 8
 9### h3
10
11* 123
12* 456
13* 789
14
15#### h4
16
17**粗體**
18_斜體_
19~~刪除線~~
20
21##### h5
22
23[超連結](https://www.google.com)

試著執行看看 Hugo 專案:

1# 加上 -D 參數會包含草稿一起秀出
2
3hugo server -D

如果順利執行完,應該就能看到套有佈景主題效果的第一篇文章了!

繼續設定樣式細節

  可以參考每個佈景主題提供的 Demo 範例,去做進一步的樣式設定,較完整的佈景主題目錄底下都會有一個「example」目錄,裡面有已經可以運行的範例可以參考(通常可以直接下 hugo server 運行起來)。

  嘗試在各種設定間找出適合自己的風格吧!

  另外 Hugo 官方文件也有提供一份標準版的 Configure 設定文件,大部分佈景主題都是以這份文件內的參數進行延伸設計:
https://gohugo.io/getting-started/configuration

發佈網站

  網站樣式和各項設定都差不多後,可以輸入以下指令:

1hugo

  指令執行完, Hugo 會在專案主目錄下建立「public」靜態網頁檔,之後就可以使用這份靜態檔發佈到各家網頁代管服務使用,舉凡 GitHub Pages 和 Netlify 都很適合當作發佈平台。

  做到這裡如果都執行順利,恭喜你已經完成了本地端的網站架設,更進一步的部署設定可以參閱其他大大的教學文章,會有更詳細和專業的說明:

Hugo Site 部署 - GitHub Pages

Hugo Site 部署 - Netlify


常用指令

整理本篇出現的常用 Hugo 指令

檢視 Hugo 版本號:

1hugo version

更新 NPM(與 Hugo 組件一起更新):

1npm update -g

創建 Hugo 專案:

1hugo new site [project name]

建立一篇新文章:

1hugo new posts/[new post name].md

本地端運行 Hugo 專案:

1# 預設運行方式
2hugo server
3
4# 包含草稿文章一起顯示
5hugo server -D
6
7# 不限發佈日期文章一律顯示
8hugo server -F

清理 Hugo 的靜態網頁檔:

1hugo --cleanDestinationDir

發佈靜態網頁檔:

1hugo

參考來源與感謝

  因為在轉職空檔有一些時間整理自己的筆記和文章,而開始萌芽翻新自己部落格的想法。

  在架設 Blog 選用技術框架期間,看了不少使用心得和實戰經驗的比較,這過程感謝撰寫這些文章的大大們,給敝人不小提醒和少走彎路的機會,本篇文章部分也是參考這些文章去撰寫,當作一個自己的心路歷程小筆記,也非常推薦大家可以進一步去看看這些文章: