| name | hugo-theme-stack |
| description | Provides Hugo Stack theme configuration reference including sidebar, widgets, comments (Giscus), color scheme, article options, custom CSS, and Stack-specific shortcodes. Use when configuring or troubleshooting Stack theme settings. |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
Hugo Stack Theme 參考
GitHub: CaiJimmy/hugo-theme-stack
params.toml 完整參考
mainSections = ["post"]
featuredImageField = "image"
rssFullContent = true
favicon = "/favicon.ico"
[footer]
since = 2020
customText = ""
[dateFormat]
published = ":date_full"
lastUpdated = ":date_full"
Sidebar
[sidebar]
compact = false
avatar = "img/avatar.png"
emoji = "💻"
subtitle = "副標題"
sidebar 會自動顯示：avatar、emoji、subtitle、main menu、social links、語言切換器、dark mode toggle。
Article 設定
[article]
headingAnchor = true
math = false
toc = true
readingTime = true
[article.list]
showTags = false
[article.license]
enabled = true
default = "Licensed under CC BY-SA 4.0"
[article.mermaid]
look = "classic"
lightTheme = "default"
darkTheme = "dark"
Per-page 覆寫：math、toc、readingTime、license、comments
Widgets
[widgets]
homepage = [
{ type = "search" },
{ type = "archives", params = { limit = 5 } },
{ type = "categories", params = { limit = 10 } },
{ type = "tag-cloud", params = { limit = 20 } },
]
page = [{ type = "toc" }]
可用 widget：search、archives、categories、tag-cloud、toc（僅 page）。
search 需要建立 content/search/index.md：
---
title: Search
layout: search
outputs: [html, json]
---
archives 需要 content/archives/index.md：
---
title: Archives
layout: archives
---
Color Scheme
[colorScheme]
toggle = true
default = "auto"
儲存在 localStorage key StackColorScheme。
Comments
[comments]
enabled = true
provider = "giscus"
[comments.giscus]
repo = "owner/repo"
repoID = ""
category = "General"
categoryID = ""
mapping = "pathname"
lightTheme = "light"
darkTheme = "dark_dimmed"
reactionsEnabled = 1
emitMetadata = 0
inputPosition = "top"
lang = "zh-TW"
strict = 0
loading = "lazy"
Giscus 需要安裝 GitHub App：https://github.com/apps/giscus
OpenGraph / SEO
[opengraph]
[opengraph.twitter]
site = ""
card = "summary_large_image"
Stack 自動產生 og:title、og:description、og:image、og:url 等 meta tag。
Image Processing
[imageProcessing.cover]
enabled = true
[imageProcessing.content]
enabled = true
Menu 設定
config/_default/menu.toml（每種語言可有自己的 menu.xx.toml）：
[[main]]
identifier = "home"
name = "Home"
url = "/"
weight = 10
[main.params]
icon = "home"
newTab = false
[[social]]
identifier = "github"
name = "GitHub"
url = "https://github.com/username"
[social.params]
icon = "brand-github"
Stack 的 icon 用 Tabler Icons：home、archives、categories、tag、search、brand-github、brand-twitter、rss
自訂 CSS
在 assets/scss/custom.scss（不是 theme 裡面）：
:root {
--accent-color: #34495e;
--card-border-radius: 10px;
--article-font-size: 1.6rem;
--article-line-height: 1.85;
}
[data-scheme="dark"] {
--body-background: #303030;
--card-background: #424242;
}
主要 CSS 變數：--body-background、--accent-color、--accent-color-darker、--accent-color-text、--body-text-color、--card-background、--card-border-radius、--shadow-l1 ~ --shadow-l4
自訂 Partials
layouts/_partials/head/custom.html — 注入 <head>layouts/_partials/footer/custom.html — 注入 </body> 前layouts/_partials/head/custom-font.html — 自訂字型
Shortcodes
{{< bilibili BV1234567890 >}}
{{< youtube dQw4w9WgXcQ >}}
{{< video src="/videos/demo.mp4" >}}
{{< quote author="Author" source="Book" url="https://..." >}}引文{{< /quote >}}
Render Hooks
Stack 內建覆寫：
- 圖片：lazy loading + PhotoSwipe lightbox
- 連結：外部連結自動
target="_blank"
- 標題：
headingAnchor = true 時加錨點
- Code block：
```mermaid 自動渲染
多語系
defaultContentLanguage 必須跟 theme 的 i18n/ 檔名一致。
Stack 內建翻譯：ar, be, bg, bn, ca, cs, de, el, en, es, fa, fr, hi, hu, id, it, ja, ko, nl, oc, pl, pt-br, pt-pt, ru, sk, th, tr, uk, vi, zh, zh-hant-tw
語言切換器在 sidebar 自動出現（當 hugo.IsMultilingual = true）。
常見地雷
- Giscus 設定 key 大小寫敏感：
repoID / categoryID，不是 repoId / categoryId
- Giscus
reactionsEnabled / emitMetadata 要用整數 1 / 0，不能用 true / false
- Giscus theme 要用
lightTheme + darkTheme 分開設，不能用單一 theme
defaultContentLanguage = "zh-tw" 會找不到 i18n，要用 "zh-hant-tw"[opengraph.twitter] 不能寫成 twitter = {}（TOML 不接受 inline empty table）
