Hugo 是使用 Go 語言編寫的靜態網站框架，號稱是這世界上最快的網站框架（好大的口氣！），人氣指數迅速竄升。本篇文章將教導你如何利用 Hugo 框架，架設到免費的 GitHub Pages，讓你在短時間內可以擁有專屬於自己的網站，免費、快速、不臃腫！

1. 建立 GitHub Pages 儲存庫

註冊一個Github帳號。

建立一個新的 Github Page Repository，點選New repository。

Repository Name 填寫使用者名稱.github.io，並選擇Public。

2. 安裝 Hugo

因為我是使用 MacOS，所以本篇文章只教 MacOS 的安裝方式，其他安裝方式請參考 Hugo 官方的Installation。

MacOS 使用者可用 Homebrew 套件安裝 Hugo。

安裝 Homebrew，打開終端機，輸入以下指令。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安裝 Hugo。

brew install hugo

輸入指令hugo version，若出現版本號，表示安裝成功。

hugo v0.122.0-b9a03bd59d5f71a529acb3e33f995e0ef332b3aa+extended darwin/amd64 BuildDate=2024-01-26T15:54:24Z VendorInfo=brew

3. 建立新網站

輸入以下指令，建立新網站。

hugo new site mysite

你可將mysite換成任意名稱。

此時mysite裡面會出現以下資料夾、檔案：

  • archetypes：Markdown 模板。
  • content：文章、頁面。
  • data：設定檔資料庫。
  • layouts：自定義樣板。
  • static：靜態資源。
  • themes：佈景主題。
  • hugo.toml：網站配置檔案。（我看有些教學文寫config.toml，但我在架設時是hugo.toml，所以你不用太介意名稱）

4. 匯入佈景主題

可至Hugo Themes挑選佈景主題。

假設是Tailwind佈景主題，依照該頁面中的說明，輸入安裝指令：

git submodule add https://github.com/tomowang/hugo-theme-tailwind.git themes/tailwind

若沒 git 的話，請先安裝 git。

brew install git

到mysite資料夾內，打開hugo.toml，找到theme，並輸入佈景主題的名稱。

theme = "tailwind"

5. 新增文章

輸入以下指令可新增文章。

hugo new post/hello-world.md

此時會在mysite/content/post資料夾裡面，建立hello-world.md，打開後可使用Markdown語法來撰寫文章。

6. 本地端測試

輸入以下指令可啟動 Hugo 伺服器來預覽網站。

預覽無草稿：

hugo server

預覽草稿：

hugo server -D

用瀏覽器打開預覽路徑http://localhost:1313/，即可看到網站。本地端伺服器啟動時，你做的任何修改，都會即時更新網站預覽畫面。

7. 部署到 Github Pages

輸入以下指令，Hugo 會建立public資料夾。

hugo

進入public資料夾。

cd public

建立本地儲存庫。

git init

加入遠端儲存庫。

git remote add origin https://github.com/使用者名稱/使用者名稱.github.io.git

加入索引。

git add .

提交版本。

git commit -m "push public"

更新遠端儲存庫資料。

git push -u origin master

發布後，在瀏覽器網址列輸入http://使用者名稱.github.io，即可看到你架設的靜態網站。

8. 其他設定

8.1 Disqus 留言板

打開配置檔Config.toml，加入以下參數。

[services.disqus]
shortname = '你的Disqus留言板Shortname'

在/layouts/partials/資料夾裡，新增disqus.html檔案，並在檔案中貼入以下官方提供的 Script。

<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="http://disqus.com/?ref_noscript"
    >comments powered by Disqus.</a
  ></noscript
>
<a href="http://disqus.com/" class="dsq-brlink"
  >comments powered by <span class="logo-disqus">Disqus</span></a
>

打開/layouts/_default/single.html，在適當位置貼入以下語法。

<div class="disqus markdown">{{ partial "disqus.html" . }}</div>

如果看不到 Disqus，請到官方 Script 中找到以下語法。

if (window.location.hostname == "localhost") return;

然後把它註解（「//」）掉。

// if (window.location.hostname == "localhost") return;

8.2 Google Analytics

打開配置檔Config.toml，找到googleAnalytics，輸入你的追蹤碼。

googleAnalytics = "G-MEASUREMENT_ID"

8.3 Google Search Console

為了讓你的網站能被 Google 搜尋到，所以必須設定 Google Search Console。

進入Google Search Console，選擇「網站前置字元」，輸入你的網站網址https://使用者名稱.github.io，如果有申請過 Google Analytics 就可以通過驗證。

進入 Sitemap，在「新增 Sitemap」中輸入sitemap.xml，提交 sitemap 網址，然後要等幾天後才會生效。

8.4 Markdown 模板

可到/archetypes/default.md，修改成你想要的 Markdown 模板， 以下是我常用的 Markdown 模板。

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
draft: false
description: ""
keywords: []
categories: []
tags: []
series: []
series_order:
---
  • title：標題
  • date：發佈時間
  • lastmod：修改時間
  • draft：true 表示為草稿狀態，false 表示為非草稿狀態。
  • description：關於該頁面的網站描述。
  • keywords：關於該頁面的關鍵字。
  • categories：分類。
  • tags：標籤。
  • series：系列名稱。
  • series_order：頁面位於該系列中的編號。
  • <!--more-->：繼續閱讀。

9. 問題解決

9.1 更新遠端儲存庫資料時錯誤

在更新遠端儲存庫資料時，會遇到錯誤訊息，這時可試試「強制更新」指令。

git push origin master:master -f

9.2 文章中的句子沒分行

在用 Markdown 語法撰寫文章的時候，發現明明要分行的句子，Hugo 預覽時卻連在一起，沒有分行成功，後來才知道要在需要分行的句尾加兩個空格。

9.3 圖片存放路徑

圖片可以存放在/static/image/資料夾裡面，用 Markdown 中寫作：

![圖片說明](/image/abc/123.png)

我的話是跟文章放在一起，例如：

content/
|
├── posts/
│ │
│ └─ abc/
│  │
│  ├── img      #圖片資料夾
│  │
│  └── index.md #文章

用 Markdown 中寫作：

![圖片說明](img/123.jpg)

9.4 測試網站架構

可以利用PageSpeed Insights這個測試網站架構工具，來看看你的網站有哪些問題需要改善。

10. 參考資料