分享我使用 Hugo 架設個人部落格的歷程，主要會講安裝，與基本使用，還有身為 Hugo 小白的我的一些心得。

另外，因個人需要有調整一些佈景 (Theme) 的 config 設置，我覺得另外寫一篇文章會比較詳細。

Introduction 說在前面

文中有些超連結文字，可能會導致你一直想點開往外查看，建議可以放到需要在更進一步了解在點過去看，因為我從來沒使用過 Hugo，所以從開始到架設完成的經歷會比較多參考。

Install 安裝

這邊的安裝說明是以 Mac 為主，我的作業系統是 macOS Catalina，若需其他系統環境的安裝方式，請參考 Hugo Getting Started - Installing 。

安裝步驟如下:

安裝 Hugo (CLI)

我選擇透過 Homebrew 安裝 Hugo。平常我習慣盡量統一用同一種方式、途徑安裝新東西，除非有其他考量(或是 brew 沒有)；安裝習慣一致後，日後遇到工作環境重置，要查找原本是如何安裝某指令時，不會忘記我曾經是怎麼安裝的，遇到的雜症會少一點。

brew install hugo

安裝成功後，執行以下指令，測試一下 hugo 指令是否可正常運作:

hugo version

# output: 
# Hugo Static Site Generator v0.74.3/extended darwin/amd64 BuildDate: unknown
# 這邊你可以看到我裝好的版本是 v0.74.3，若你有一天遇到新版有問題時，也歡迎留言跟我分享。

建立站點 (Site)

# hugo new site your-site-name
# for example
hugo new site my-hugo-blog

安裝佈景 (Themes)

你可以到 Hugo Themes 選幾個看起來 ok 的佈景；我習慣是要先選到一個比較符合我想要的感覺的佈景，才會決定使用這個工具，所以在還沒開始做這些動作時，光是佈景就挑了好幾天，為節省正在觀看文章的你一點時間，在此提供幾個方向做參考:

1. 整體樣式: 你曾經看過的部落格樣式，你想要用跟他相似的，或是想用成一樣的
2. 文章風格: 例如你要專寫技術文章，可以透過 Hugo Theme 右側列出的 tag 去查找
3. 內外佈局: 文章展開 (more) 前後的感覺，是否要有側邊欄 (Menu)，或導航列 (Navbar) 等
4. 選單圖案: 佈景提供的 Menu 連結搭配的 icon 樣式、排列，與感覺
5. markdown style: 佈景 demo 通常會有 markdown showcase 文章供你參考
6. code block style: 佈景的 code block 是否方便透過 config 替換樣式、顯示行號
7. shortcode: 額外工具，例如 Highlight Text 、數學公式、流程圖繪製、 GA 、評論系統等

在你備選的幾個佈景輪流試用中，根據每種佈景作者提供的參數，去切換參數設置看看，你才知道哪些是可隨你意思做動的部分，而哪些是你以後寫文章會需要常用到的。

我是從「佈局」與「整體感覺」先挑出幾個候選，然後每種我覺得會用到的工具都設定試試看；在還沒決定工具之前，我先用了 jekyll ，但選不到我想要的佈景，且看了幾套後覺得 go 很潮 Hugo 標榜速度超快，所以跳來 Hugo，試用了 Even 與 Tranquilpeak 之後，才決定用後者。

以我自己使用的佈景為例，我沒有透過 git submodule 的方式安裝，而是直接 clone 到本地，將 clone 下來的專案放到 hugo site 資料夾 themes 底下，跟透過 submodule 設置是同樣意思。

# 在專案資料夾底下
git clone https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/tranquilpeak

# themes 資料夾是用來專門放置佈景的
# 特地將 hugo-tranquilpeak-theme 重命名為 tranquilpeak，在設置 config 時指定佈景名稱比較方便

Usage 基本使用

hugo 指令搞定後，site 建立完成，佈景設置好，基本的就剩「文章操作」、「發布上線」這兩件事。

Create Post 新增文章

hugo new post/my-first-post.md

稍微說明一下，post/xxx.md 這個結構是: 資料夾/檔案名稱+markdown 副檔名，指令執行之後，檔案會長在 /content 底下，例如 /content/post/filename.md

<a href="https://github.com/olOwOlo/hugo-theme-even#installation" target="_blank">Even</a>

Edit Post 編寫文章

文章內容主要是由 Markdown 語法編寫的，可參考 Markdown 語法說明 ，我較常用的有:

• H1 - H6 標題: 運用此語法來產生 toc 目錄
• > 區塊引言: 我都使用佈景提供的 hl shortcode，比較少用 markdown 的 >
• *, -, + 清單: 也就是在每行文字前面加上項目符號
• 1., 2. 有序清單: 也就是在每行文字前面加上有序序號，通常我不會遞增序號(從頭到尾都用 1.)，這樣方便抽換順序
• tab 縮排: 適當的使用縮排可以讓行與行之間有段落區別
• 程式碼區塊: 我習慣使用三個 ` 成對去包住程式區塊，參考 Code and Syntax Highlighting

蠻多的就不在此一一列舉。

Delete Post 刪除文章

Hugo 刪除文章的方式就是直接把檔案給移除就好。

Local Running 本地執行

在你尚未把網站發布公開，或是文章還沒完成發表 (Publish) 前，通常會在本地寫文章、修修改改，直到吿一個段落；你可以透過執行以下指令，並打開 localhost:1313 查看網站發表後的樣子:

hugo server -D

# or `hugo server` running without `draft: true` post

hugo 目前版本都已有 Live Reload 模式，我們不用特別下指令 (舊版貌似要用 watch 還是啥)，也就是 server running 期間，修改配置、文章，都會馬上渲染生效。

本地打包 Hugo

本地打包就是把你當前的 Hugo 專案，包成一整個可被訪問的靜態資源，產出到資料夾 public，日後你要把網站整個發布到線上時，就是把 public 整包丟到你的 web server 上，不用在另行編譯；你也可以透過指定 publishdir 來變更產出的資料夾名稱。

hugo

# output (like):
#                     | ZH-TW
#  -------------------+--------
#    Pages            |     2
#    Paginator pages  |     0
#    Non-page files   |     0
#    Static files     |     9
#    Processed images |     0
#    Aliases          |     2
#    Sitemaps         |     1
#    Cleaned          |     0
#  
#  Total in 72 ms

發佈到線上 Web Server

最後，關於要把網站放到線上、公開讓別人閱覽，以及設置個人網址這部分，會另外在寫一篇文章說明。

References 參考連結

我盡量把我準備過程中，造訪過的連結都放在這，建議若你現在不需要，不一定要全都看懂才開始。

• Hugo Quick Start
• Hugo Getting Started - Installing
• Hugo Getting Started - Usage
• Hugo Theme - Tranquilpeak
• Who's using Tranquilpeak Hugo Theme
• Hugo Themes Tranquilpeak Tags-plugins-showcase
• Hugo Directory Structure
• Hugo hosting-on-github

Modification 修訂內容

• 2020-09-02 新增「文章分類」與「文章標籤」用法
• 2020-09-02 把「文章」部分內容拆出去「文章操作
• 2020-09-04 修改排版，把小項目標題改為 H2 方便從目錄去選擇
• 2020-09-04 新增 Series 系列文章
• 2020-09-08 新增 Series 系列文章 貼身打造個人部落格 - 03. 網站發布
• 2020-09-08 暫時把坑移除

Series 系列文章

• 貼身打造個人部落格 - 01. 安裝 (本篇)
• 貼身打造個人部落格 - 02. 文章 Front Matter
• 貼身打造個人部落格 - 03. 網站發布