# Hugo > Provides Hugo static site generator reference for configuration, templates, content management, and multilingual setup. Use when modifying Hugo site config, creating templates or shortcodes, managing content structure, or debugging Hugo build issues. - Skill: `recca0120/hugo` (Agent Skill) - Install (CLI): `npx skillmds@latest add recca0120/hugo` - Raw SKILL.md: https://api.skillmd.com/api/skills/recca0120/hugo/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: recca0120 (https://skillmd.com/u/recca0120) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/recca0120/hugo --- # 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 常用設定 ```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 ```yaml --- 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 ```toml [zh-hant-tw] languageName = "正體中文" weight = 1 [en] languageName = "English" weight = 2 ``` 注意：`defaultContentLanguage` 必須跟 `languages.toml` 的 key 完全一致，也要跟 theme 的 `i18n/` 檔名一致。 每個語言可以有自己的 `menu.xx.toml`。 模板裡用 `relLangURL` / `absLangURL`，不要寫死路徑。 ## 模板系統 ### 查找順序（高到低） 1. 專案 `layouts/` > theme `layouts/` 2. 語言特定 > 通用 3. Type 特定 > `_default/` ### 常用覆寫位置 ``` layouts/ ├── _partials/head/custom.html # 注入 （JSON-LD、meta） ├── _partials/footer/custom.html # 注入 前 ├── _markup/render-image.html # 自訂圖片渲染 └── _default/single.html # 覆寫單篇頁面 ``` ### Go Template 語法速查 ```go {{ .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 常用指令 ```bash hugo server -D # 本地預覽（含草稿） hugo --gc --minify # 正式建置 hugo new content post/slug/index.md hugo list drafts # 列出草稿 hugo config # 印出合併後設定 hugo env # 版本 + 環境資訊 ``` ## 常見地雷 - `baseURL` 漏尾斜線或 protocol → 路徑全壞 - `index.md` vs `_index.md` 搞混 → page bundle 失效 - `enableGitInfo = true` 在 CI 需要 `fetch-depth: 0` - SCSS 需要 Hugo Extended 版本 - `resources/` 快取目錄可以 commit 加速 CI - `.` 在 `range`/`with` 會變 context，用 `$` 存取外層