前言

這幾年有越來越多開發者選擇將 blog 放在以下服務中

一方面是這些服務支援使用 Markdown 寫作，另一方面是可以直接增加 side project 的曝光程度。

不過因為 github 服務較廣為人知，所以一般來說教學文章與大眾選擇都是 github 居多，不過在多方比較後，發現其實架設在 gitlab 上面其實比 github 簡單，而且 blog 的原始檔案可以使用 private repo 的形式存放，不用擔心會被人 fork 或是 dowload 一份，瞬間將整份內容都搬走，另外就是 gitlab 與 CI/CD 整合得很好，可以在 blog 中直接將部屬設定好，過幾分鐘後線上就會更新。

內文

工具

  • Hugo
    • version 0.51
  • Visual Studio Code
    • Better TOML
    • Markdown All in One

在撰寫工具的使用上面，有很多可供選擇，像是老牌的 Jekyll，不過這次選用相對年輕很多的 Hugo，一方面是夠年輕，另外一面是安裝與使用夠簡單。

Hugo 在官方網站上面有一篇很簡單的安裝教學，連結。

若用 Mac 的話使用 brew 安裝無難度 brew install hugo 就結束了，若是 windows 的話其實可以考慮使用 binary 檔案，抓下來後其.exe檔案路徑存入環境變數中，就可以在命令列中使用，也是相當無腦的安裝方式。

其實這邊若是不想安裝 Visual Studio Code 的話也是可以用任一款編輯器來撰寫文章，當然若有支援 Markdown 的話可以寫的更加便利。

在 Mac 上面若是開發者基本上可以考慮裝一下 Visual Studio Code 很多套件可以用，也支援很多語法高量與自動完成。若不想安裝的話也還有很多 Markdown 編輯器 (MacDown, Bear, Markdown Monster…族繁不及備載)

ps. Markdown Monster 是 Windows 平台

Gitlab

repo 準備

開啟一個 repo 名稱為 {user_name}.gitlab.io

可以是 public 也可以是 private，將 url 設定好

git remote add {git repo url}

Hugo

新增 site

安裝好之後皆下來第一步就是將整個 project init 好

  • 首先切換到欲儲存 project 的位置

  • hugo new site {SiteName}

  • 以上！就這樣完成了準備了

基本上會有幾個資料夾的東西，會需要特別注意。在撰寫新完張的時候， hugo 會將文章存放於 posts 這個資料夾之下，而基本上會把產出的結果放在 public 這個資料夾，若沒有出現的話可以執行 hugo 這樣他就會產生出來。

public 裡面的內容就是用 themes 和 content 裡面的東西產出來的靜態檔案，也就是要被發佈出去的內容。

ps. 這邊 public 這個資料夾名稱是可以自行設定的，不過基本上會建議不用改這個值，因為這個命名夠直覺

若是要當作自己的部落格的話，gitlab會需要將site name命名為「{user_name}.gitlab.io」若是 github 的話需要將名字命名為「{user_name}.github.io」

安裝 template

架設個人部落格若樣式太平凡就顯現不出個人色彩了，所幸 Hugo 有一個 template 集散地讓使用者不但可以分享自己的 template 也可以將這些 template 下載下來直接使用，或甚至自行做調整。

官網的教學相當簡單

git submodule add {template git url} themes/{template_name}

雖然使用 git 的 submodule 是官配，但那是對於不調整 template 的人才比較方便，若是有自行調整 template 的需求，我會比較推薦直接將 template 下載下來，做完調整後將他當作自己 repo 的一部份，當然若當心的話請選擇 license 沒有問題的版本(基本上那邊很多都是 MIT 版本，沒有這個問題)

配置文件

這份文件對於 hugo 來說相當重要

官方說明文件 連結

這份設定檔可以傳入 theme 需要的參數（舉凡，分頁、multi language、auther、theme name、custom css…）其中 baseUrl 這項若是用在個人部落格的話請跟 Site Name 一樣，並加上 url scheme (https / http)。

另外，其中的 publishdir 值是指執行 hugo 指令後產生的結果要輸出到那個資料夾，這邊預設就會是 public，若沒有特別的想法就別改了。

寫新文章

指令也很簡單

hugo new article_name.md

這樣就會在 content 下產生一個新的 md 檔，不過為了方便整理建議用以下方式新增文章

hugo new posts/path_1/article_name_1.md

這樣文章就會產生在 posts 資料夾底下 path_1 資料夾裡面，若執行當下沒有 path_1 名稱的資料夾則會自動產生。

產生出來的檔案中，裡面會有些預先生成的內容與設定。

其中 draft 這個設定很重要，預設會是 true 這表示在執行指令 hugo 後並不會將此文發佈出來，若文章已經寫好的話記得要將這個值設為 false，不然可是會看不到的。

另外，若遇到文章中有圖片的話，我自己是習慣將圖片同樣放在 posts 裡面，在另外新增一個資料夾「images」裡面再用文章名稱分類，將各文章會用到的圖片作歸檔。

取用時將連結設定到相對的位置(ex. posts/path_1/images/image_name.jpg)這樣就能正確讀到指定的圖片了。

Hugo 本身也支援語法高量，支援種類眾多，可以參考官方的文件。

ps. 若你習慣將靜態內容集中放在同一處的話，可以放在static這個資料夾中。新增一個images資料夾，並把文章中的圖片分好類放在這邊也是不錯的選擇

本機預覽

這個功能還滿好用的，尤其是執行之後每次對文章進行的更動都能即時的刷新預覽，而且預覽狀態下連同 draft 版本的文章都還是可以看到！(這是 Options 參數，需要主動打開)

hugo server -D

Hugo Options Official docs

ps. 把 -D 參數去掉的話就是看到實際發佈時的狀態

生成靜態業面

hugo

是的，就這麼一行。預設會產生在 public 資料夾，也會是部屬時也是針對此資料夾的內容部屬。

部屬

這個算是我偏好將部落格架在 gitlab 的原因之一。其實 Hugo 官方有教學。

在根目錄中新增檔案，名稱是「.gitlab-ci.yml」，內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

image: monachus/hugo

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

好了，完成這些動作後，當你 git push 到 gitlab repo 後就會自動觸發建置，稍微等個幾分鐘就可以看到文章已經順利發佈出來了。