Hexo到Hugo 遷移過程紀錄

前言

這篇說是搬遷紀錄，如果真的只寫紀錄的話，可以借鑑的部分一定很少，所以會順便介紹 Hugo，即使之前沒有寫過部落格的，也可以參考這篇建置。

搬遷動機

其實主要原因只是衝動，但多少是一些使用過程中遇到的問題導致，不是說這個生態系不好用，我還是比較推薦 Hexo 作為新手入門使用，畢竟它本身是 JS 寫的，官方文件看不懂，還可以直接去找原始碼看懂，(శωశ)。

以下列出兩個面向，一是 Hexo 本身，二是我使用的這套 hexo-theme-hueman 主題。

很難保證使用者可以無腦升級環境和套件版本

Hexo 是用 JS 寫的，不免俗的是使用 Node.js/npm 組合包，而我在開發環境升到 Node.js ^14 後，最低限度的建置和發佈功能就壞掉了，查詢其他人回報同樣問題的解決方式，居然都是要環境降版，官方也回答不要用最新的環境，其實這種問題也不一定是 Hexo 自身的問題，有可能是相依套件的鍋，不過我就甩到它身上。
主題為了使用外部參數，必須使用樣板語言，但又很難用

乍看之下好像沒什麼，主題其實很方便，載好放到指定目錄即可，但我有客製的需求，主題不是用 EJS ，就是 Pug，改起來滿有難度的，而且一改就很難拉主題的最新更新。

建置步驟

安裝

windows 去 Hugo GitHub 的 Releases 找安裝檔

macOS 用 Homebrew 裝，$ brew install hugo

建立站點

$ hugo new site <site_name> 建好後，裡面的目錄結構長這樣

.
├── archetypes  # 新文章樣板，後面建文章的部分解釋
├── config.toml # 設定檔，非常重要，預設格式為 toml，可改為 yaml / json
├── content     # 放文章，結構後面說
├── data        # 沒用到，官方說明是用來放置靜態資料，再用官方樣板語言讀取
├── layouts     # 沒用到，因為已套用主題的 layouts，官方有規定結構，自製要注意
├── static      # 靜態檔放置處，放 images、css、js
└── themes      # 主題放置處，下個步驟解釋

下載主題

到 Hugo Themes 挑選，挑好後想辦法把它抓下來，塞到/themes資料夾裡，官方建議使用的git submodule非常不方便，如果完全不想改主題再使用，不然直接下載或是git clone會比較方便客製
之後到設定檔config.toml，增加這行，theme = "<theme_name>"，theme_name自行替換為/themes裡的主題資料夾名
主題所在的 GitHub Repo，找找 README，找到主題的擴充設定，通常也會是config.toml，全部複製貼上到自己的設定檔，後面邊預覽邊調整細項

建立新文章

執行這行指令
```
$ hugo new posts/my-first-post.md
```
這個步驟有幾個細節
- 指令中的posts，會使用/archetypes內的posts.md作為樣板生成後面的檔案，若樣板不存在則使用default.md，注意這裡會優先使用/themes/<theme_name>/archetypes
- 建出來的檔案位置是，/content/posts/my-first-post.md
- 此時若開啟預覽，文章網址預設在，/posts/my-first-post
- 預設的default.md樣板的Front Matter會取得檔名，並經過"{{ replace .Name "-" " " | title }}"，轉換為my first post
```
# default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
---

# my-first-post.md
---
title: "my first post"
date: 2021-02-01T14:15:59-06:00
draft: false
---
```
開發預覽
```
$ hugo server -D
# -D，連同草稿( draft: true )一起編譯
```
此時注意，不管是設定檔修改，還是新增文章並修改，都可以即時預覽，不用重開

發佈

因發佈是我自己的流程，和前面的步驟段落分開，新手可參考，或是找其他人的方法

到 GitHub 建立新 Repo，Repo 名隨意，用來放置除發佈資料夾以外的開發檔案，記得在.gitignore 忽略public/、resources/，之後包含主題全部推上遠端，後續要自己不定時推上遠端
到 GitHub 建立新 Repo，Repo 名使用每個帳號唯一一個主網域，<GitHub_Id>.github.io，修改設定檔內的baseURL等於 Repo 名，執行建置指令$ hugo，進入/public，建立 git，所有內容推上遠端，後續更新只要執行建置→進入/public→推遠端即可

補充

文章結構 & 建檔腳本

因朋友啟發，若文章數量變多易導致管理不易，我的/content資料夾結構如下

/content
  └──posts
      ├───2020
      |     ├───01
      |     ├───02
      |     ├───03
      |     ...
      |     ├───11
      |     └───12
      └───2021
            ├───01
            ├───02
            |    └───2020-02-01-my-first-post.md # 檔案依照年月放置，並且檔名自帶日期
            └───03

別忘了上面有說，檔案放的位置和名稱會影響網址，但我不可能讓文章網址是/posts/2021/02/2020-02-01-my-first-post

這時候參考官網的URL Management，在設定檔中增加 [permalinks] posts = "/posts/:year:month/:slug"，設定之後的網址是/posts/202102/myfirstpost

網址搞定之後，覺得如果每次建立新文章，要手動調整檔案到指定格式，或是打一長串指令

$ hugo new posts/2021/02/2020-02-02-my-second-post.md

太麻煩了，所以寫了一個腳本，可以自動生成檔案，並且避免檔案內的標題抓到日期

# newPost.sh

if ! command -v hugo &> /dev/null
then
    echo "hugo command could not be found"
    exit
fi

read -p "Input New Post Name: " POSTNAME

TODAY="$(date '+%Y-%m-%d')"
YYYY=$(date '+%Y')
MM=$(date '+%m')
BASIC="posts/${YYYY}/${MM}/${POSTNAME}.md"
FULL="posts/${YYYY}/${MM}/${TODAY}-${POSTNAME}.md"

hugo new $BASIC

mv "${PWD}/content/${BASIC}" "${PWD}/content/${FULL}"

如上，自己建個檔案，把上面這段貼進去儲存，執行後只要打上檔名即可，再現跟 Hexo 一樣的體驗

$ sh newPost.sh
Input New Post Name: <type_your_new_post_name>
post created!

發佈腳本

同樣麻煩，一樣寫了個腳本

# deploy.sh
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo

cd public/

# Add changes to git.
git add .

# Commit changes.
# rebuilding site 2021年 2月1日 週日 21時33分47秒 CST
msg="rebuilding site `date`"
if [ $# -eq 1 ]
    then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

同樣重現 Hexo 體驗，執行發佈檔即可，可多寫一個參數作為 commit 的內容

$ sh deploy.sh
-----------
$ sh deploy.sh <custom_commit_message>

結語

應該可以從各方面看出我對新工具還不太熟悉，一方面是功能很多，另一方面是 Hugo 的官網不像 Hexo 有官方繁中文件

反正現在基本的部落格建起來了，需要新功能再研究囉～