概念 on 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 每個語言就是獨立一個 site，每個 site 各自獨立，多語言網站中每種語言都是 language 這個維度上的一個 site，本篇說明具體應該如何設定。

Sites Matrix

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

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

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 的模板查找機制，查找機制決定每個頁面該套用哪個模板，主要由三個基本概念決定：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 回收。

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 支援一個頁面可以同時擁有多種輸出格式，此功能透過 output formats 進行設定。