recca0120 Hugo 靜態網站產生器參考
設定檔結構
config/_default/
├── hugo.toml # 核心設定（baseURL、theme、語言、分頁、permalink）
├── params.toml # 主題參數
├── menu.toml # 選單（可依語言拆分：menu.en.toml）
├── languages.toml # 多語系
└── markup.toml # Markdown 渲染設定
環境覆寫：config/production/params.toml
hugo.toml 常用設定
baseURL = "https://example.com/" # 必須有 protocol 和尾斜線
title = "Site Title"
theme = "theme-name"
languageCode = "zh-TW"
defaultContentLanguage = "zh-hant-tw"
hasCJKLanguage = true
timeZone = "Asia/Taipei"
googleAnalytics = "G-XXXXXXXXXX"
enableGitInfo = false # 需要完整 git history
[pagination]
pagerSize = 10
[permalinks]
post = "/:year/:month/:day/:slug/"
[taxonomies]
tag = "tags"
category = "categories"
[outputs]
home = ["HTML", "RSS", "JSON"] # JSON 給搜尋用
Permalink token：:year :month :day :slug :section :title :contentbasename
Content 管理
Page Bundle（Leaf Bundle）
content/post/my-article/
├── index.md # 預設語言
├── index.en.md # 英文版
└── featured.png # Page resource
Branch Bundle 用 _index.md，Leaf Bundle 用 index.md，混用會壞掉。
Front Matter
---
title: "文章標題"
description: "SEO 摘要，160 字元以內"
slug: url-slug
date: "2024-01-15T09:00:00+08:00"
image: featured.png
categories:
- Category
tags:
- Tag1
- Tag2
draft: false
---
關鍵欄位：
slug只覆寫最後一段 URL；url覆寫整個路徑draft: true不加-D不會發布weight控制排序（數字小的在前）aliases做舊 URL 轉址
多語系
檔名策略
content/post/slug/
├── index.md # 預設語言
└── index.en.md # 英文
languages.toml
[zh-hant-tw]
languageName = "正體中文"
weight = 1
[en]
languageName = "English"
weight = 2
注意：defaultContentLanguage 必須跟 languages.toml 的 key 完全一致，也要跟 theme 的 i18n/ 檔名一致。
每個語言可以有自己的 menu.xx.toml。
模板裡用 relLangURL / absLangURL，不要寫死路徑。
模板系統
查找順序（高到低）
- 專案
layouts/> themelayouts/ - 語言特定 > 通用
- Type 特定 >
_default/
常用覆寫位置
layouts/
├── _partials/head/custom.html # 注入 <head>（JSON-LD、meta）
├── _partials/footer/custom.html # 注入 </body> 前
├── _markup/render-image.html # 自訂圖片渲染
└── _default/single.html # 覆寫單篇頁面
Go Template 語法速查
{{ .Title }} {{ .Content }} {{ .Permalink }} {{ .RelPermalink }}
{{ .Params.image }} {{ .Site.Title }} {{ .Site.BaseURL }}
{{ if .IsPage }}...{{ end }}
{{ with .Description }}{{ . }}{{ end }}
{{ range .Pages }}...{{ end }}
{{ .Date.Format "2006-01-02T15:04:05Z07:00" }} # Go 的 reference time
{{ .Title | jsonify }} # JSON 安全輸出
{{ .Summary | plainify | truncate 160 }}
$ 在 range/with 裡存取最外層 context。
CLI 常用指令
hugo server -D # 本地預覽（含草稿）
hugo --gc --minify # 正式建置
hugo new content post/slug/index.md
hugo list drafts # 列出草稿
hugo config # 印出合併後設定
hugo env # 版本 + 環境資訊
常見地雷
baseURL漏尾斜線或 protocol → 路徑全壞index.mdvs_index.md搞混 → page bundle 失效enableGitInfo = true在 CI 需要fetch-depth: 0- SCSS 需要 Hugo Extended 版本
resources/快取目錄可以 commit 加速 CI.在range/with會變 context，用$存取外層