請啟用 Javascript 查看內容

Hugo 建立 Blog

 ·  ☕ 6 分鐘

這週是 六角鼠年鐵人賽 第七週，挑戰剛開始時，我的文章是放在 Bloggi，而且第一週文章就是 Bloggi 如何使用（明顯混分😂），但後來想想，Bloggi 沒有留言、沒有備份、嵌入 CodePen 會跑版，為了避免之後不必要的麻煩，還是用自己建立一個 Blog 吧。

Featured Image

GitHub Pages

架設部落格最頭痛的問題就是放網站的空間，通常架設網站不是自己用 NAS 來架設，就是花錢租主機空間。

以上兩種方法都是需要一定的花費，但是透過 GitHub Pages 來架站，則完全免費，但也有一定的 條件：

  • 網站大小不能超過 1 GB
  • 網站每月流量不能超過 100 GB
  • 一小時內的網站更新不得超過 10 次

以上限制對一般需求一定夠用，而且 GitHub 是著名的軟體原始碼代管服務，有一定的穩定性。

要說唯一的缺點，就是 GitHub Pages 只能架設「靜態網站」，因此無法架設 Wordpress 之類的部落格。

這時候就需要使用到 靜態網頁產生器 來建立 Blog。

1. 熱門靜態網頁產生器

Hugo 簡介

Hugo 官網

Hugo 是一個用 Go 語言編寫的靜態網站生成器，最大的優點就是編譯速度相對於 Jekyll、Hexo 簡直是飛快。

  • 基於 go 語言開發，沒有錯綜複雜的依賴關係
  • 社區活躍
  • 功能完善
  • 前端語言支持的種類豐富
  • 整體框架靈活易懂
  • 修改即時預覽

近期有越來越多人因為 Hugo 的編譯速度，將部落格從 Hexo 搬移到 Hugo，不過 Hugo 也有一個很大的缺點，就是相對 Hexo 來說，Blog 的主題太少，也是有人因為 Hexo 有喜歡的主題而捨棄 Hugo。

搭建 Hugo

1. 前置作業

MacOS 可以直接使用 Homebrew 安裝 Hugo。

brew install hugo

在 Windsow 環境必須先下載 hugo_extended_0.67.0_Windows-64bit.zip。

解壓縮後，會有一個 hugo.exe 檔案。創建一個新資料夾：C:\hugo，並將 hugo.exe 檔案放到裡面。

接下來配置環境變數，點選本機（右鍵） > 內容 > 進階系統設定 > 環境變數 > Path > 編輯 > 新增路徑：C:\hugo。

2. 建立一個專案

開啟終端機並切換到 hugo/ 資料夾下，執行以下命令：

hugo new site myBlog

myblog 可以替換成任意名稱。

機器上會產生一個 myBlog 資料夾，結構如下：

myBlog/
│
├── archetypes/
│ │
│ └─ default.md  # 預設 markdown
├── content/     # 頁面、文章（markdown）
├── data/        # 資料庫
├── layouts/     # 自定義的樣板
├── static/      # 靜態資源
├── themes/      # 網站的主題
└── config.toml  # 網站的配置

3. 加入主題

因為 Hugo 預設沒有任何主題的，因此必須在 Hugo Themes 選擇一個來套用。

記得先安裝 git 工具，接下來在 myBlog/ 資料夾下加入 git 版控：

git init

從 Github 下載主題並將其添加到 theme 目錄中：

git submodule add https://github.com/AmazingRise/hugo-theme-diary.git themes/diary

如果沒安裝 git：

  • 可以直接下載該主題最新版本，並解壓縮；
  • 將資料夾重新命名 並將其移至 themes 資料夾。

最後開啟跟目錄下的 config.toml 檔案，設定使用主題：

theme = "diary"

或是將 theme/ 內的 config.toml 取代根目錄的。

最基本的主題安裝流程大概是這樣。

但要注意，因為 config 配置檔，支援 toml、yaml、json 三種格式，也可以放在 config/ 資料夾內，然後拆分不同模組的配置。所以並不是每個主題的安裝方式都相同，因此最好詳細閱讀每個主題下方的說明。

4. 新增頁面

hugo new 會根據 archetypes/ 資料夾下的 default.md 產生在 content/ 資料夾下。

hugo new [路徑]頁面名.md

單頁面，一般會放在 content/ 資料夾下，例如：

hugo new about.md

文章一般會放在 content/posts/ 內，例如：

hugo new posts/my-first-post.md

不同的主題，會有不同的資料夾結構，單頁面與文章的 Front Matter 設定也都不相同，因此可以查看主題文件說明。

5. 本地端測試

預覽草稿 Draft：

hugo server -D

預覽（不包含草稿）：

hugo server

預覽網址：http://localhost:1313/

建議在本地測試時，config.toml 設定檔內的 baseURL 先設為空值。

自定義

1. Front Matter

Front-matter 是 md 檔案最上方的分隔區域，用於指定個別檔案的變數。

預設使用 yaml 格式，使用 --- 分隔：

1
2
3
4
5

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

另外還支持 toml、json 格式，分別使用 +++ 與 {} 分隔。

預設屬性分別為：

  • title：標題名，使用 hugo new 建立會與檔名相同。
  • date：日期，使用 hugo new 建立為目前時間。
  • draft：草稿，如果是 true 生成網站時，不包括此頁面。

1.1 常用 Front Matter 屬性

另外，列出其他 Hugo 支持的常用 Front Matter 屬性：

  • description：內容描述，主要用於 SEO 優化。
  • tags：標籤。
  • categories：分類。
  • keywords：關鍵字。
  • url：文章 url 名稱，預設使用檔案名稱。
  • weight：列表頁的文章排序，越小越靠前，無設定則依照時間排序。

其他屬性，主要看你用的主題所對應到板模上的變數，主題的文件都會詳細說明。

1.2 Archetypes

Archetypes 意思為原型，可以當作是生成 md 檔案的模板。

當我們使用 hugo new 建立 md 檔案時，會根據 archetypes/ 資料夾下的模板來建立。

舉例來說，如果 archetypes/ 下有一個 about.md，那麼以下指令就會根據它來產生檔案。

hugo new about.md

如果沒有相同的檔名，會根據 default.md 來產生檔案。

2. Config

Hugo 將整個網站的設定配置都集中在 config.toml 檔中，預設為 toml 格式，一樣支持另外兩種格式（yaml、json）。

完整 Hugo Config 可以詳閱官方文件 Configure Hugo。

發佈到 Github Pages 上

Host on GitHub

事前準備：

  • 安裝 Git 2.8 以上
  • GitHub 帳號
  • Hugo 網站

1. 建立 repository

在 GitHub 建立一個 repository，命名為：帳號.github.io。

2. 設定 baseURL

將 config.toml 配置檔內的 baseURL 設為：

1

baseURL = "http://帳號.github.io/"

3. 建立 public 資料夾

hugo

執行 hugo 就會產生 public/ 的資料夾。

4. 上傳

在 public/ 資料夾下執行以下命令：

git init
git remote add origin https://github.com/帳號/帳號.github.io.git
git add .
git commit -m "my Blog"
git push -u origin master

接下來可能會讓你輸入你的 Github 帳號和密碼，之後就可以去 Github 和 http://帳號.github.io 查看是否成功。

5. 更新

之後添加文章，只需要重新編譯 Hugo，重新提交到 Github 即可。

git add . 
git commit -m "本次更新的說明"
git push origin master

新增留言板

因為是靜態網頁，所以留言板就區要依賴第三方。

Disqus 是整合性留言管理系統，用來管理各種社群的留言平台。

1. 註冊帳號

註冊帳號並取得 shortname。

流程蠻簡單的，如果不清楚，可以自行搜尋一下教學流程，這裡就不多做說明。

Language 如果選擇 Chinese 只有簡體。

2. 在 Hugo 啟用

假設你的主題已經預設 Disqus 留言板了，那麼只需要在config.toml 配置檔填入 Disqus 的 shortname。

1

disqusShortname = "yourdiscussshortname"

如果沒有，就需要將官方提供的檔案加到你的網站中。

在 layouts/partials/ 資料夾下，加入 disqus.html 檔案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

<div id="disqus_thread"></div>
<script type="text/javascript">

(function() {
    // Don't ever inject Disqus on localhost--it creates unwanted
    // discussions from 'localhost:1313' on your Disqus account...
    if (window.location.hostname == "localhost")
        return;

    var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
    var disqus_shortname = '{{ .Site.DisqusShortname }}';
    dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="https://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>

如果要在本地端測試 Disqus，可以將 if (window.location.hostname == "localhost") return; 註解掉。

最後開啟你主題內的 layouts/_default/ 資料夾中的 single.html 在適當位置貼上下面這段：

1

{{ partial "disqus.html" . }}

這樣就完成了。

Google Analytics

1. 建立帳戶

前往 Google Analytics，可以使用 Google 帳號，直接註冊。

建立帳戶取得 Tracking ID。

2. Hugo 設定

在 config.toml 加入 Tracking ID：

googleAnalytics = "UA-XXXXX-Y"

在主題內的 layouts/partials/ 資料夾中的 head.html 在適當位置貼上下面這段：

1

{{ template "_internal/google_analytics_async.html" . }}

容易遇到的問題

1. Markdown 圖片路徑

在 Markdown 圖片路徑中，是以 static/ 為根目錄寫全路徑。

圖片位置：/static/imgae/cover/post1.png，那麼在 Markdown 中寫作：

1

![圖片說明](/imgae/cover/post1.png)

總結

目前就先記錄到這，之後如果有用到 Hugo 其他功能再補上。

文章部分，之後會慢慢把 Blogger 的舊文搬過來，還有 Hackmd 的筆記整理後丟過來 🙂

竹白
作者
竹白
前端筆記
文章目錄