Hello Hugo

去年針對文件持續交付找了一些工具，當時以 K8s 官方網站作為目標，研究他使用的工具以及架構，後來這件事情就沒有時間持續往下。最近想把個人的入口網站，做更完善的整理，試了一些東西，最後腦海還是出現去年研究 Hugo 的想法，所以整理一下研究的筆記。

現況與背景

現在 (2020/01) 的 Blog 主要使用 Hexo，大約從 2015 年到現在，文章總數 257，每次發布執行 hexo generate，底下是執行過程：

~ % hexo generate
INFO  Start processing
INFO  Files loaded in 4.95 s
... 略 ...
INFO  Generated: 2019/10/19/AWS/Study-Notes-EKS_Networking/index.html
INFO  Generated: 2019/08/25/Management/Problems-of-Meeting/index.html
INFO  Generated: 2019/09/09/AWS/Whitepaper-Using-AWS-For-Disaster-Recovery/index.html
INFO  Generated: 2019/08/14/About/About-Certificate/index.html
... 略 ...
INFO  783 files generated in 2.43 min
~ %

在 macbook pro (SSD, 2015Late) 上的執行時間約要花 2.43 min.

同樣的資料量，把現在 Blog 的文張放到 Hugo 跑本地端的：

~$ hugo server -D

                   | EN
+------------------+-----+
  Pages            | 293
  Paginator pages  |  27
  Non-page files   |   1
  Static files     |   3
  Processed images |   0
  Aliases          |   2
  Sitemaps         |   1
  Cleaned          |   0

Built in 1034 ms
Watching for changes in /tmp/gtcafe/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /tmp/gtcafe/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

效能差非常的多。除了效能，另外我想要擴展 Blog 這件事情，讓他變成我的 Portal Site，去年談文件持續交付的過程，以 K8s 官網為研究對象，覺得 Hugo 應該是可以投資、嘗試的。

Experience Hugo

先體驗一下 Hugo，從安裝 Hugo、新文章、測試、到發布一個網站，整理六個步驟的完整流程。

底下是在 macOS 執行。

# 1. 安裝 hugo
~$ brew install hugo
## 1.1 確認版本, 筆記當下的最新版本是 v0.62.2
~$ hugo version
Hugo Static Site Generator v0.62.2/extended darwin/amd64 BuildDate: unknown

# 2. 初始化 Static Site
~$ hugo new site gtcafe
Congratulations! Your new Hugo site is created in /tmp/gtcafe.
# 2.1 切換到 site 目錄
~$ cd gtcafe

# 3. 下載 theme: ananke, 存放在 themes/ananke
~$ git clone https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

# 4. 產生一篇文章
~$ hugo new post/my-first-post.md

# 5. 啟動 hugo server, 同時指定 theme, 不忽略 draft 內容
## 瀏覽 http://localhost:1313
~$ hugo server -D --theme=ananke

# 6. 產生靜態資料, 存放到 /public 目錄, 將 public 裡的資料放到 github 或 靜態網站服務器.
~$ HUGO_ENV=production hugo

## Hugo 原生提供 benchmark
~$ hugo benchmark

順利的話，步驟五會看到以下的結果：

Hello Hugo

底下紀錄 Hugo 模組相關概念、流程，更細部的說明後續再持續整理。

Installation

底下是安裝 Hugo 的完整紀錄。

# -------------
# 安裝
# -------------
## 在 macOS 安裝 Hugo
~$ brew install hugo
## 已經安裝過了，用以下方式 Upgrade.
# ~$ brew upgrade hugo

## 確認版本，筆記當下的最新版本是 v0.62.2
~$ hugo version
Hugo Static Site Generator v0.62.2/extended darwin/amd64 BuildDate: unknown

# -------------
# 初始化 Static Site
# -------------
~$ hugo new site gtcafe
Congratulations! Your new Hugo site is created in /tmp/gtcafe.

Just a few more steps and you re ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

目錄結構

建立好一個 Site 之後，Hugo 產生了一個基本的結構，包含文件內容、Themes、配置 … 等，預設會產生以下目錄結構：

~$ tree
.
├── archetypes/     # 文章的樣板類型庫，通常會有 blog、docs、news .. 等類型。類似 java maven 的 archetypes 概念。
│   └── default.md
├── config.toml     # config 配置檔，支援 toml、yaml、json 三種格式。
|                   # 也可以放在目錄 (config/) 裡，然後拆分不同模組的配置。
├── content/        # 存放文章原始檔的目錄，主要以 markdown 為主
├── data/           # 存放配置檔
├── layouts/        # 網站的樣板 (template) 檔
├── static/         # 靜態檔案目錄，像是 css / js / fonts / images ... etc.
└── themes/         # 主題目錄，預設沒有

詳細參閱： Directory Structure

Config

Hugo 提供很多參數讓使用者自行配置，底下幾個是我在配置時遇到的、值得留意的：

baseURL: 網站的 FQDN，像是 https://blog.rick.com/
paginate: 分頁數目，預設是 10
permalinks: URL 的結構，如果要從其他 blog 轉過來，就要另外配置，詳細參閱 URLs
- 像是從 hexo 過來: posts = "/:year/:month/:day/:slug/:title/"
taxonomies: 配置 catagories、tags、series 等，詳細參閱 Taxonomies
- disablePathToLower: Hugo 預設會把 url 大寫轉為小寫，這參數可以關閉 Path 轉小寫
- preserveTaxonomyNames: 關閉 Catagoery、Tags、Series 轉小寫，預設為 false。Hugo 預設會把 Taxonomy（Categories、Tags、Series）名稱轉為小寫
contentDir: 指定 content 的目錄點，像是多語系網站，預設會設計成 /content/en/ 開始的 landing Page，而不是 post 之類的位置。
theme: 使用的主題 (theme)，會去目錄 /theme/{THEME_HAME} 讀取相關資料，沒有指定的話，則會直接讀取根目錄底下的 layouts、static.

其他過程中我有遇到，但通常不用特別改的：

menu: 設定網站的選單使用，詳細參閱 menu
跟建置有關的參數：
- buildDrafts: 建制的時候，包含標記草稿的內容，預設是 false
- buildExpired: 建制的時候，包含已經過期的內容，預設是 false
- buildFuture: 建制的時候，包含未來要發布的文章，預設是 false。
defaultContentLanguage: 預設語系
enableRobotsTXT: 產生 robots.txt
frontmatter: 與時間有關的設定，詳細參見 Front Matter
googleAnalytics: GA
hasCJKLanguage: 雙位元語系國家，包含日文、韓文、中文。
imaging: 影像處理的配置，詳細參見 Image processing

Config 有修改的話，有些需要重啟 server 才會生效，像是 permalinks

完整 Hugo Config 參閱： Configure Hugo

佈景主題 (Themes)

下載佈景主題 (Theme) 並測試，Themes 可以到這裡下載：https://themes.gohugo.io/

~$ cd gtcafe
~$ git init

## 底下是我試過的
~$ git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
~$ git submodule add https://github.com/dim0627/hugo_theme_robust.git themes/hugo_theme_robust
~$ git submodule add https://github.com/digitalcraftsman/hugo-material-docs.git themes/hugo-material-docs

## 測試佈景主題，建議先不用急著配置 config.toml
## 而是用底下測試方法測試 theme，找到喜歡的 theme 之後，再開始修改 config.toml
~$ hugo server -D --theme=ananke
~$ hugo server -D --theme=hugo_theme_robust
~$ hugo server -D --theme=hugo-material-docs

## 確立要哪一個 theme 之後，寫入 config.toml
# ~$ echo 'theme = "ananke"' >> config.toml

Theme 的目錄結構大致包含以下：

# Structure of hugo-material-docs
.
├── archetypes          # Theme 設定的 archetypes
├── exampleSite         # 範例，通常複製這個目錄底下到 Site 根目錄就可以看到。
├── layouts             # 主要的 Theme Template 都在這裡。
└── static              # 靜態資料，像是 fonts, images, css, js

其中 archetypes、layouts、static 這三個目錄通常都會有，另外通常也都會有一個 exampleSites 目錄，存放範例資料，也就是 theme 提供的的範例資料。

使用 theme 的方式有兩種：

第一種是直接在 config.toml 指定 theme 的名稱，然後把 exampleSites 目錄裡的資料複製到 site 的根目錄。
- 這種方式通常是要單獨開發 Theme 給其他人使用
第二種是直接把 theme 裡的三個主要目錄複製到 Site 根目錄，把原本的目錄蓋過去。

官方建議使用第二種。

本地端測試

跟 Hexo 同樣，hugo 同樣可以起一個 WebServer 執行測試。

# -------------
# 建立新文章
# -------------
~$ hugo new post/my-first-post.md

# -------------
# 本地端測試
# -------------
## 包含 Draft (草稿) 文章
~$ hugo server -D
~$ hugo server -buildDrafts

## 產生靜態資料，發布使用
## 執行後，會在 public 目錄產生可以發佈的靜態資料，可以直接放到 github 或者 s3 發布。
~$ HUGO_ENV=production hugo
                   | EN
+------------------+----+
  Pages            |  7
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  1
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Total in 70 ms


## 執行 production mode.
~$ HUGO_ENV=production hugo server

文章

hugo 的文章都放在 content 目錄裡，同樣的也是以 markdown 作為格式，如下：

---
date: 2016-03-08T21:07:13+01:00
title: Material for Hugo
type: index
weight: 0
---

## Beautiful documentation

Material is a theme for [Hugo](https://gohugo.io), a fast and flexible static site generator. It is built using Google's [material design](https://www.google.com/design/spec/material-design/introduction.html)
guidelines, fully responsive, optimized for touch and pointer devices as well
as all sorts of screen sizes.

![Material Screenshot](/images/screen.png)

Material is very lightweight – it is built from scratch using Javascript and
CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts
and Analytics). Yet, it is highly customizable and degrades gracefully in older
browsers.

Q and A

Q: Hugo 有 category or tag 的功能？

有的，Hugo 稱為 Taxonomies，包含了 Catagoery、Tags、Series 三中，詳細參閱 Taxonomies

Q: 文章的圖檔應該擺哪裡？

放在 /static 目錄裡面即可。這個位置就是靜態資料在擺放的。

Q: 放在 /content 裡的文章 (markdown)，有時候放在 /content/post/、有些放在 /content/blog/，到底應該放在哪個位置？

這其實跟 Theme 的設計有關係，每個 Theme 對於 Content 的設計與定義不一樣，以 Theme ananke 為例，找到 /layouts/index.html，其中的 $mainSections 就是定義用哪一個路徑，預設是 post。

結論

簡單整理 hugo 基本的用法，因為看到 K8s 官網，我相信 hugo 可以達到我想要的，想要的以及未來方向整理如下：

需求 (許願池)

Blog: 需求如同 Hexo Tuning 描述的需求。
使用體驗改善，像是更簡潔的介面、支援 Landing Page、RWD … etc.
考慮 SEO: URI 設定
- 假設要從 hexo 搬過來，那麼勢必要能夠處理舊的 URI.
Docs: Blog 算是流水帳的形式，但我希望可以像鳥哥或者良葛格那樣，針對特定主題，持續整理成有系統的、屬於自己的知識庫，取代掉 Blog 鬆散的結構。
個人品牌：
- 有 AMP (Accelerated Mobile Pages) 功能，可以讓 Blog 直接變成像是 Native APP 那樣，直接在本地端使用。
- 個人客製化的 Theme

工作流程

考量未來經營 blog 與個人 KM 的積累，有以下流程：

Blog -> Docs: 比較隨性，沒有嚴謹架構的隨筆，先以 Blog 形式發佈
1. 先在 Blog 寫成文章：把想法記錄下來，持續修改、或者蒐集相關資訊。
2. 定期整理到 Docs，文章蒐錄到 Docs 之後，Blog 就不再更新。
Docs -> Blog: 主題與結構式整理, 先想整個架構，然後一一落筆。
1. 整理出大的藍圖、目錄、結構
2. 一一把文章整理出來。
3. 反饋到 Blog，公告。

雜感

研究 Hugo 設定的過程，看到很多以前設計 ^{1, 2} 過的影子，特別是 Config 的結構與設計，像是 Config 得階層、Config 的動態變數、Config 注入的方式有靜態 (config.toml)、動態 (CLI 參數以及環境變數 starts with HUGO_) … 等設計，這些其實都是一個成熟系統設計的基本原則與實踐方法。

Hello Hugo

現況與背景

Experience Hugo

Hello Hugo

Installation

目錄結構

Config

佈景主題 (Themes)

本地端測試

文章

Q and A

結論

需求 (許願池)

工作流程

雜感

延伸閱讀

站內資料

Comments

About

著作

演講

Facebook

AWS Certifications