部落格從去年一月至今也快滿兩年了，中間一直有想修改部落格的樣板，經過一陣選擇與研究以後，決定連產生器也換掉試試看，於是就轉到了 Hugo。Hugo 是一個以 golang 為基礎開發的靜態網站產生器，他的建置速度很快，目前感覺他的操作指令以及目錄規劃也蠻乾淨好上手。這篇就筆記一下我從 jekyll 轉換到 hugo 的過程及一些重點。

Step 1: 環境安裝

　　因為我平常主要比較習慣使用 Linux Bash，因此我是把 hugo 安裝在 WSL，不過 Ubuntu 自帶的 Hugo 版本比較舊，我建議直接去 github 抓最新的 Release 版 deb下來安裝，安裝完以後可以執行 hugo version 指令，確認安裝是否成功以及安裝版本。

$ sudo dpkg -i hugo_VERSION_Linux-64bit.deb
$ hugo version

　

Step 2: 初始化部落格

　　初始化的流程還蠻簡單的，我就直接在每行指令說明：

# 建立部落格目錄，目錄名稱可以自己決定
$ mkdir hugo-site
$ cd hugo-site
# 初始化 git，之後我們會使用 git 做版本控管
$ git init
$ git commit --allow-empty -m Init
# 初始化 hugo
$ hugo new site . --force
# 測試
$ hugo serve -D

　　執行完 hugo serve -D 以後，可以到 http://localhost:1313/ 確認一下是否有架起來，這個指令之後會很常用。有架起來的話應該會看到一個空白網頁，畢竟我們什麼都還沒放進去嘛 ～ 如果有問題的話應該會顯示無法連上該網站之類的錯誤。

　　另外 public 和 resources 這兩個目錄是 hugo 建置時會產生的，可以把他們加入到 gitignore 裡面。

　

Step 3: 加入樣板主題

　　主題可以到 Hugo Themes 去找自己喜歡的來套，都有預覽可以看。

　　Hugo 主題的程式碼是放在 themes 底下，hugo 官方教學使用 git submodule 來追蹤，但我不是很喜歡 git submodule 的設計，而且我也已經預期會自己動手改造樣板，也沒有打算很認真追蹤上游的修改，因此我是使用 git subtree 指令來把主題的 git tree 直接合併到我的 git tree 上：

$ git remote add gohugo-theme-ananke https://github.com/budparr/gohugo-theme-ananke.git
$ git fetch gohugo-theme-ananke
# 以下建立 branch 是 workaround，不確定為什麼 git subtree 在沒有其他 branch 的情況下有時候會出錯
$ git co -b theme
$ git co master
# 加入 subtree
$ git subtree add -P themes/gohugo-theme-ananke gohugo-theme-ananke master
# 指定 theme
$ echo 'theme = "gohugo-theme-ananke"' >> config.toml

　　加入 subtree 以後可以使用 tig 或是其他 git 工具，可以看到 theme 的 git 分支已經合併到我們的主線上了：

　

Step 4: 加入測試文章

　　到這步以後，網站的雛型已經差不多出來了，可以先加個測試用的文章試試看，hugo 的文章都是放在 content 目錄下，可以使用 hugo new 指令來協助建立

# 建立一篇新文章到 content/posts/my-first-post.md
$ hugo new posts/my-first-post.md
# 測試
$ hugo serve -D

　　一樣到 http://localhost:1313/ 看一下目前網站的情況，應該已經可以看到第一篇文章了。

　

Step 5: 搬移舊文章

　　用 Markdown 寫文章的好處就是相容性比較好，但也只有比較好而已。一些轉換的工具可以參考官方的 Migrate 文章。我但試用了幾個方法以後發現還是有地方需要人工調整，研究了一段時間，我最後選擇的是 ConvertToHugo，他是一個簡單的 python script 做 markdown 文章的轉換，所以有一點程式能力的話可以再稍作微調，減少手工的部分。

以下記錄幾個轉換要注意的點

  1. 每篇文章的 url
    • hugo 可以指定每一篇文章的位址，確定最終位址跟原本的一樣，否則位址更換後，搜尋引擎的搜索紀錄都會錯誤
  2. 每篇文章的 date、lastmod、author
    • 轉完最好確認一下有符合預期
  3. 內文的超連結
  4. code block 和內嵌 html 的部分

文章轉換完以後，還有一些部落格的設定要記得檢查修改，這些大部分會在 config.toml 裡面

  1. Blog Title
  2. Google Analytics
  3. Discus
  4. 其他的個人外部網站連結，例如 Github、FB 以及 About Me 等等
  5. CNAME

　

Step 6: 發布新部落格到 github

　　hugo 建置網站的指令非常簡單，只需要執行 hugo，他就會把網站建置好並放到 public 資料夾內。

　　和 jekyll 比較不一樣的是，由於 github 不支援直接建置 hugo 的專案，因此要發布的話，要把建置出來的 public 目錄 push 到原本在 yourname.github.io 的專案，而不像 jekyll 只需要 push 建置前的就好。

　　所以最後會有兩個 git project，其中一個是包含整個 hugo 專案的原始碼，另一個是要建置好的網站程式碼。hugo 專案原始碼可以放在 private 的 github 專案，或是你想放在其他代碼託管網站都可以，而建置好的網站程式碼則是推到 yourname.github.io 的專案裡面。

　　至於原本的 jekyll 專案，我是直接把他 rename 到其他的 branch，以下指令因為會涉及到刪除指令，請確定理解每個指令的行為，小心操作

# 在原本的 jekyll 專案內執行以下指令
# 建立新 branch
$ git co -b jekyll
# 把新 branch 推到 remote
$ git push origin jekyll
# 刪掉 master branch
$ git br -d master
# 刪掉 remote 的 master branch
$ git push --delete origin master
# 建立一個獨立的新 master branch
$ git co --orphan master
# 之後把 hugo 建置好的 public 資料夾內容推到 master branch 即可

　　Hugo 的教學文件有提供一個簡單的 script 來讓你快速執行發布這件事情，他也是使用 git submodule 來達成這件事，但我不太喜歡 git submodule，所以我稍微改了一下，讓他變成一般的獨立 project，可參考以下的 script，第一次執行我建議先一行一行手動執行看看。

#!/bin/sh

# If a command fails then the deploy stops
set -e
printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Clear Public folder (這行我註解掉了，請確定知道這個指令會執行什麼，再解除註解)
# rm -r public

# Clone project
git clone https://github.com/YOUR_PROJECT.git public

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -s -m "$msg"

# Push source and build repos.
git push origin master

　

搬遷心得後記

　　目前的感想是 hugo 還蠻簡單好上手的，而且也換了一個好修改的樣板主題，所以這次的搬移算是非常值得。雖然寫在後面已經有點晚了，不過我的建議是，如果會想要客製化樣板主題，建議要好好挑選，找個簡單精練的會比較容易去改。