主頁 on Hugo 社群文檔

認識 Hugo

Sat, 15 Aug 2026 04:09:57 +0800

Hugo 是以 Go 語言撰寫的靜態網站生成器 (SSG)，構建的靜態網站讓你免於煩惱伺服器的開銷和維護問題。Hugo 有諸多特色，速度只是其中一個，設定靈活、可規模化、可擴展性以及開箱即用都只是他的眾多優點之一。

安裝 Hugo 以及其工具鏈

Sat, 15 Aug 2026 04:09:57 +0800

本篇說明如何在各作業系統安裝 Hugo，並設定好執行所需的環境變數（PATH）。

入門

Mon, 01 Jan 0001 00:00:00 +0000

本文假設讀者已經對程式語言有基礎認知，不會從零介紹所有程式知識，並且在這個基礎認知上介紹 Hugo 的語法。

介紹

Mon, 01 Jan 0001 00:00:00 +0000

本章節是參考，列出所有 Hugo 內建工具。

專案結構與 UFS

Mon, 01 Jan 0001 00:00:00 +0000

專案結構

標準的 Hugo 專案結構如下：

my-project/
├── archetypes/ # 新內容的預設樣板
├── assets/ # 可經 Hugo Pipes 處理（CSS、JS、圖片）
├── static/ # 不會被處理，原樣複製到輸出目錄
├── config/
│ ├── _default/ # 預設設定
│ │ └── hugo.yaml # 網站設定檔，也可放在專案根目錄
│ └── production/ # 環境專屬的覆寫設定
├── content/ # Markdown 內容
├── data/ # 供模板讀取的自訂資料檔（JSON/YAML/yaml）
├── i18n/ # 翻譯檔
├── layouts/ # 模板檔案，網站的 HTML 結構
├── public/ # 建置輸出目錄
├── resources/ # 資源處理快取
└── themes/ # 主題（若透過 git submodule 安裝）

其中 resources 和 public 每次構建都會重複生成，你應該將這兩個目錄設定到 .gitignore 中，因為 Git 追蹤被生成的檔案沒有任何意義。

內容管理

Mon, 01 Jan 0001 00:00:00 +0000

本文介紹與 content 目錄所有有關的內容。

建立網站

Mon, 01 Jan 0001 00:00:00 +0000

本文說明如何使用 Hugo 建立網站並啟動本地開發伺服器。

建立專案

hugo new project my-site
cd my-site

hugo new project 會建立基本的目錄結構，此時網站還沒有任何主題與內容。

基礎語法

Mon, 01 Jan 0001 00:00:00 +0000

計算和比較

Hugo 沒有 +、< 這些符號，比較需用函式呼叫。

內容撰寫

Mon, 01 Jan 0001 00:00:00 +0000

本篇說明撰寫文章內容會用到的相關知識，包含 content 目錄結構，Markdown、front matter 與 shortcode。

資源處理

Mon, 01 Jan 0001 00:00:00 +0000

resource.Resource 物件用於 Hugo 的資源處理。

建立

有多種方式可以建立 resource.Resource 物件，以全局函式來說有以下幾種方式：

多語言網站

Mon, 01 Jan 0001 00:00:00 +0000

Hugo 每個語言就是獨立一個 site，每個 site 各自獨立，多語言網站中每種語言都是 language 這個維度上的一個 site，本篇說明具體應該如何設定。

開發設定

Mon, 01 Jan 0001 00:00:00 +0000

本文介紹 Hugo 開發相關設定。

編輯器設定

VS Code 語法高亮和補全：theNewDynamic/language-hugo-vscode
JetBrains 語法高亮和補全：Smart Hugo

Formatter 設定

HTML

可以使用 prettier 插件以格式化 HTML + go-template。

Sites Matrix

Mon, 01 Jan 0001 00:00:00 +0000

在 Hugo 中每個語言都是獨立的 site，而 Hugo v0.153.0 進一步引入了 sites matrix 概念，將原本單一維度的「一個 language 對應一個 site」提升到三個維度的組合。本篇說明這個概念，以及如何用它控制內容的產生範圍。

基礎設定

Mon, 01 Jan 0001 00:00:00 +0000

Hugo 的設定檔有上百個選項可以設定，初學者看到一定會非常迷惑，本文的目的是整理出 hugo.yaml 中最值得關注的設定，讓你不會在大量的設定中迷路。

Hugo Modules

Mon, 01 Jan 0001 00:00:00 +0000

本文專門介紹 Hugo Modules 以及對應的 hugo mod 指令。

什麼是 Module

Module 是 Hugo 組織內容的基本單位。一個 module 可以是完整的 Hugo 專案，也可以只是提供某一種元件（content、layouts、assets、data、i18n、static、archetypes）的小型可重用套件。你安裝的主題，本質上就是一個 module。

網址與路由

Mon, 01 Jan 0001 00:00:00 +0000

這篇文章說明 Hugo 如何決定每個頁面的網址。從一開始就把網址管理做對，失效連結對網站的傷害幾乎大於一切，因此要及早規劃好你的做法。

模板系統

Mon, 01 Jan 0001 00:00:00 +0000

本文介紹 Hugo 的模板查找機制，查找機制決定每個頁面該套用哪個模板，主要由三個基本概念決定：page kind、page type，以及 front matter 手動指定的 layout。理解基本概念之後，我們會介紹完整的模板分類，才真正說明完整的查找順序，在文章的最後搭配兩個範例總結本文。

Data

Mon, 01 Jan 0001 00:00:00 +0000

Data 目錄只儲存三種檔案：yaml, YAML, JSON。這個目錄的特色是在 Hugo 啟動後，該目錄的內容就會被讀取到 Hugo 記憶體中直到構建結束，中間不會被清除。因此，如果有很大、不被多頁面共用的結構性文件，則應該放在 assets 目錄中，因為 assets 裡面的內容處理完成後，佔用的記憶體會被 GC 回收。

部署網站

Mon, 01 Jan 0001 00:00:00 +0000

將你的網站部署到公開網路上，Hugo 官方做了非常詳盡的教學，請見官方文檔。

Content Adapter

Mon, 01 Jan 0001 00:00:00 +0000

Content Adapter 用於建立動態頁面，通常用於建立 API 文檔，透過前置腳本建立好 JSON 的結構化文件，然後在 content adapter 中讀取 data 檔案並自動建立頁面。使用請見官方文檔。

設定檔索引

Mon, 01 Jan 0001 00:00:00 +0000

請見 Hugo 官方文檔的設定檔索引頁面。

API 索引

Mon, 01 Jan 0001 00:00:00 +0000

你可以把 Hugo 開發理解成 Hugo 語言，他封裝了 Go 語言的功能提供給模板使用，並且自行解析模板、reflect 變數，可以說是自成一家的語言了。Go 語言的功能僅有有限的提供，因此即使你熟悉 Go/Go template，使用 Hugo 還是得看文檔才會使用。

建立主題

Mon, 01 Jan 0001 00:00:00 +0000

這篇文章帶你從零建立主題，做中學更快理解，你說對吧。

建立專案

hugo new project my-blog --format=yaml
cd my-blog

CSS 樣式表

先把樣式準備好，CSS 和模板無關，這裡直接複製一個簡易範本到 assets/css/main.css 即可。

輸出格式

Mon, 01 Jan 0001 00:00:00 +0000

Hugo 支援一個頁面可以同時擁有多種輸出格式，此功能透過 output formats 進行設定。

CLI 索引

Mon, 01 Jan 0001 00:00:00 +0000

以下索引整理自 Hugo 官方文檔，本站不重複撰寫這些內容，直接連回官方頁面查閱即可。

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

連結檢查

可以整合外部工具連結正確性，如 rumdl MD057 規則支援 Markdown 連結以及資產，以及絕對連結偵測和補全。