前言

說起建立自己的部落格,網路上也是可以找到千千百百種做法。而其中最多人用來製作部落格的就是 Hexo 跟 Hugo 兩種了。
這篇文章算是舊文了,但近期翻了一下覺得可以重寫一篇加上一些新的內容所以就這麼做了。
希望能幫到需要的人~

說到靜態網頁產生器,不外乎就是大名鼎鼎的"H雙兄弟" – Hexo & Hugo 啦!

Hexo 是基於 Node.js 的靜態網頁產生器,而 Hugo 則是基於 Go 語言。
兩者除了名字上長得有那麼一點像以外,其他地方也有很多相似之處。但我們今天就專門針對 Hugo 來寫一篇教學筆記。
之所以會想要選 Hugo 就是因為大家好像都用 Hexo 比較多,所以我就來試試小衆口味好了~
(其實是我覺得 Hugo 比較快)

那麼我們開始吧。

安裝

首先,如果是使用 mac,可以用 Homebrew 安裝 Hugo

brew install hugo

如果是 Windows,則可以使用 Chocolate 來安裝:

choco install hugo -confirm

如果是 Linux,我相信你一定早就知道怎麼裝了吧?(誤

接下來,我們建立一個新的部落格,並且初始化 git

hugo new site my-blog -f yaml # -f 表示使用 yarm 作爲部落格設定的格式
cd my-blog
git init

為部落格加入一個 主題
這邊使用 Blogpaper當作範例

git submodule add https://github.com/NormandErwan/Blogpaper themes/Blogpaper
echo 'theme: "Blogpaper"' >> config.yaml

建立文章

那麼接下來,我們要在部落格內新增第一篇廢文文章:

hugo new posts/my-first-post.md

你可以編輯你剛剛建立的新文章
它的位置應該會在 content/posts/my-first-post.md

打開那個檔案看看,一開始的內容會類似下面這樣:

---
title: My First Post
subtitle: # Optional, will be displayed bellow the title of the page; remove this line to generate an automatic subtitle
date: 2020-08-14T21:33:07+08:00
categories: # Optional, will be displayed above the title of the page
- First category
- Second category
tags: # Optional, will be displayed at the bottom end of the post
- First tag
- Second tag
summary: # Optional, will be diplayed on the homepage; remove this line to generate an automatic summary (see https://gohugo.io/content-management/summaries/)
draft: true
banner:
  #src: my-first-post.jpg # Optional, the filename of the banner, by default my-first-post.jpg
  caption: # Optional, the caption of the banner
  href: # Optional, a link on the caption
---

這串在 Markdown 上方的內容是稱爲 Front-matter,也就是針對個別文章的資料做設定的地方。
相關設定可以參考官方說明

現在我們在 Front matter 區塊下方 --- 的下方加上我們的文章內容:

## Hello, world

這是我的第一篇 Hugo 文章。

然後我們稍微整理一下 Front matter,現在我們的文章檔案會如下方這樣:

---
title: Hello World
subtitle: 
date: 2020-08-14T21:33:07+08:00
tags:
- hello
- first-post
- hugo
summary: 我的第一篇 Hugo 文章
draft: true
---

## Hello, world

哈囉!這是我的第一篇 Hugo 文章。

啟動 Server

文章新建完成後,我們來啟動本機的 Hugo server 看一下我們的新部落格長的什麼樣子吧!
打開終端機執行下列指令:

hugo server -D

這邊的 -D 代表著將我們的草稿(draft, 也就是在剛剛文章的設定檔當中的參數)也一併的顯示出來。
到時候如果要將部落格部署到線上時, draft 參數設定為 true 的文章是不會被打包進去的。

如果想要預覽部署之前的樣子,可以使用這個指令:

hugo server

在啟動 Server 後,我們就可以到瀏覽器訪問 hugo 幫我們建立的網站連結(預設為localhost:1313)

噹啷,現在我們有一個部落格了,儘管長得很醜就是了XD

A hugo blog with one post but no images

加入圖片

爲了美化我們的部落格,接下來我們來爲部落格新增一些圖片吧。
就先以這兩張當作範例:

A banner image with text 'hugo'

上面這張當作部落格的 banner

An iPad on a newspaper on the desk

而第二張當作我們的文章 banner

做法很簡單,
首先將圖片存到 content/ 並將圖片命名爲 banner,接著我們建立一個 content/_index.md 而不必填入內容。

接著我們在調整一下 content/posts/ 當中的結構。建立一個資料夾名爲 my-first-post/ 並將我們原本的 my-first-post.md 移到當中並改名爲 index.md。隨後加入我們的文章的封面圖片並命名爲 banner

到這邊,專案的結構應該會如下:

.
└── content
    ├── posts
    |   └── my-first-post
    |       ├── banner.jpeg
    |       └── index.md
    ├── _index.md
    └── banner.jpg

回到瀏覽器看看,應該會看見我們已經有兩張圖片,分別為首頁的 banner 以及我們文章的 banner。

A hugo blog with a post and contains banner images

太好了,你現在有了自己的 Blog,可以開始盡情地發廢文了!

不過目前為止的樣子應該還是很混亂,沒關係,我們可以做一些設定。

設定

此節可參考官方說明

Hugo 官方預設使用 config.yaml|toml 作為設定檔,格式可參考: TOML, YAML。以下範例使用 .yaml

基本設定範例如下:

baseURL: http://my-blog.com # 部落格網址
languageCode: zh-TW # 語言代碼
title: KY Chang's Blog # 部落格名稱
theme: "Blogpaper" # 主題名稱,對映到 themes/blogpaper/
copyright: (c) 2020 KY Chang # 著作權聲明
author: # 作者資訊
  name: KY Chang

架構

Hugo 的文章內容都存在 content/posts/ 路徑底下,可以建立子資料夾來管理文章,也可以直接以單一檔案來儲存。

資料夾

以建立一篇文章標題為 new-post 為例,
可在 content/post 下建立 new-post/ 路徑,加入 index.mdbanner.jpg,banner 將會自動套入。

也可以在文章當中另外加入其他圖片資源:

content/
  posts/
    new-post/
      index.md
      banner.jpg
      image1.png
      image2.png

圖片引入方式,在一開始生成的範例文章 Style Guide 中都有說明。

單一檔案

如果沒有其他的圖片等等資源需要放的話,可以直接建立單個檔案作為文章,banner 圖片則需與文章檔案名稱相同:

content/
  posts/
    new-post.md
    new-post.jpg

Favicon

Hugo 設定 Favicon 的方法非常簡單,建立一個 static/ 路徑並將 favicon.ico 放到裡面就可以了!

cd my-blog
mkdir static/
mv favicon.ico static/

以上就是最基本的 Hugo 使用,更多詳細的架構問題可以參考他們的 官方文件

部署

我們將使用 GitHub Page 來做靜態網站的部署,並且會搭配 GitHub Action 幫我們做簡易的 CI/CD

依照 Hugo 官網的教學來進行配置。

我們只需要建立一個設定檔 .github/workflows/gh-pages.yaml,內容如下:

name: github pages

on:
  push:
    branches:
      - main # 觸發 GitHub Action 的分支

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/[email protected]
        with:
          submodules: true # GitHub Action 會依據 .gitmodule 幫你抓取你的主題,如果你不是使用 gitmodule 這裡可以關掉
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/[email protected]
        with:
          hugo-version: "latest"
          extended: true # 如果你有使用 sass/scss 這裡請設定為 true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/[email protected]
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # 這個 Token 為 GitHub 自動產生
          publish_dir: ./public

簡單講解一下這個文件設定的步驟。

首先我們設定了 main 這個分支作爲偵測 GitHub Action 的分支,一旦這個分支有內容更新, GitHub 就會自動幫我們執行這個設定檔當中我們接下來所定義的動作。

Setup Hugo 這個意思就是在進行 GitHub Action 的伺服器上建立一個包含 Hugo 服務的環境,接著 Build 這個動作就會將我們的網站打包成預備上線的版本,最後 Deploy 就是透過 actions-gh-pages 這個官方提供的腳本將打包完成的檔案從 public 這個路徑複製並更新到 gh-pages 這個分支上。

gh-pages 這個分支就是我們存放網站文件的地方。

提交更新

設定完成之後,我們就可以提交我們的更新並觸發 GitHub Aciton。

在這之前,我假設你已經在 GitHub 上面建立一個 Repository 並設定好 git remote,如果這個部分需要協助可參考 GitHub 官方文件

那麼我們就進行提交:

git add .
git commit -m "release: my first blog"
git push origin main # 這邊我使用 main 作主分支,如果你是用 master,可以字行提換(上面的 yaml 設定也記得換)

然後我們前往在 GitHub 上的 Repository 頁面,點擊 Action 進入 GitHub Action 頁面:

Github repository page and with the highlight action button

你會看到這個 GitHub Action 的畫面,紅色框框的部分應該會依照我們剛剛所提交的訊息來顯示:

Github action workflow page

如果有出現綠色勾勾,那就代表我們的 CI/CD 自動化流程順利執行完畢,如果點擊提交訊息可以進入查看腳本執行過程的記錄。
而如果正在執行腳本,他也會即時顯示給你看,相當有意思。

好的那麼最後我們前往 repository 的 setting 處,往下會看到一個標示為 GitHub Pages 的段落,這邊我們要把 Source Branch 選擇為我們剛剛在在 CI/CD 過程中部署的所在分支: gh-pages

Github setting page with the github page config section, gh-pages branch was highlight

好的,最後我們等待幾分鐘之後,GitHub 就會幫我們建立一個 GitHub page,我們可以造訪該 GitHub page 的連結來查看我們的部落格!

這邊說明一下:GitHub Page 分為 Personal pageProject page 兩種。
Personal page 的 repository name 限定為 <yourgithubusername>.github.io,而 Project page 則沒有限定。
而 Personal page 對應的連結為 https://<yourgithubusername>.github.io,Project page 則是 https://<yourgithubusername>.github.io/<your-project-repository-name>

如果有需要關於自訂網域相關的設定教學,歡迎留言或寄信給我,我可以再整理一篇筆記分享一下我踩過的雷。

以上就是如何快速優雅的使用 Hugo 建立部落格並透過 GitHub Action 部署的方法啦!

總結

Hugo 真的是一個還不錯用的靜態網頁建構工具,最近我才把我的 Hugo 主題改造成我自已喜歡的樣子,之後有機會我也會把它做成可分享的版本發佈給大家使用。
有空的話也寫一篇分享怎麼製作 Hugo 主題好了(有空的話…遠望QAQ)。

那本篇文章就到這邊啦,繼續展開寫扣發廢文的人生了。

“我不是正在發廢文,就是在思考要發什麼廢文。” – 佚名文學家

“我發廢文,故我在。” – 佚名哲學家