Hugo on dongxiaoqi's Blog

Stack 主题个性化定制实录

Thu, 13 Aug 2026 11:12:00 +0800

一、背景

Stack 主题切换上线后（见《博客主题从 MemE 切换到 Stack 实录》），博客外观与基础链路就绪。此后围绕头像、导航、视觉细节、字体、评论与社交做了一系列个性化定制，本文记录这些改动及其背后的取舍与踩坑。整个过程延续「无本地 hugo、直接靠 CI 验证」的工作方式，每个改动都是一次 push → 触发构建 → curl 线上确认的闭环。

二、改动清单

1. 博客头像

用户提供了一张《猫和老鼠》指挥家横图（1102×689）。Stack 侧边栏头像经 helper/image.html 的 .Resources.Get 解析，而 .site-logo 的 CSS 没有 object-fit（默认 fill 会拉伸），直接用横图会被拉变形。

处理：用 Pillow 把原图中心裁成正方形 689×689，存 assets/img/avatar.jpeg，config 里 [params.sidebar] avatar = "img/avatar.jpeg"，原图备份为 avatar-source.jpeg。

1
2
3
4
5
6


from PIL import Image
img = Image.open("avatar-source.jpeg")
w, h = img.size
s = min(w, h)
left = (w - s) // 2
img.crop((left, 0, left + s, s)).save("avatar.jpeg")

关键点：头像必须在 assets/ 下（Stack 用 Hugo Resources 解析，不是 static/），且文件扩展名要与实际文件一致，否则 .Resources.Get 匹配不到。

2. 分类菜单 404 修复

切换后点侧边栏「技术 / 随笔 / 关于」全跳 404。排查发现菜单 url 配的是 /categories/tech/（categoryMap 的小写英文 key），但 Notion Action 把文章的 Notion Category（中文 select 名「技术/随笔/关于」）原样写进 front matter 的 categories: 字段——categoryMap 只决定 content/zh 下的子目录名，不影响 front matter。Hugo 按 front matter 的 categories 生成分类页，实际路径是中文 /categories/技术/，与菜单对不上。

1
2
3


# 实测验证
curl /categories/tech/ -> 404
curl /categories/技术/ -> 200

修复：把菜单三个 url 改成 Hugo 实际生成的中文路径 /categories/技术/、/categories/随笔/、/categories/关于/。随笔暂无文章，/categories/随笔/ 仍 404，等有文章后自动出现，保留菜单项占位。

教训：Notion→Hugo 链路里，分类页 URL 由 front matter 的 categories 决定，不由文件目录决定；改菜单前先 curl 确认 Hugo 实际生成的路径。

3. 页脚跳动的心

参考 guanqr.com，在版权行末尾加一颗 Font Awesome 实心心形，用 fa-heartbeat 双跳动画（1.3s 循环）。通过覆盖主题 partial 实现，不动 submodule：

layouts/_partials/footer/footer.html：版权行追加
layouts/_partials/footer/custom.html：注入心跳 @keyframes CSS（主题留空的扩展点）

1
2
3
4
5
6
7
8


@keyframes heartbeat {
 0% { transform: scale(1); }
 14% { transform: scale(1.3); }
 28% { transform: scale(1); }
 42% { transform: scale(1.3); }
 70% { transform: scale(1); }
 100% { transform: scale(1); }
}

细节：心形红色 #ff4d4f，1em 尺寸随字号缩放，vertical-align 对齐基线；加 @media (prefers-reduced-motion: reduce) 守卫，系统开了「减少动态效果」时停止动画（无障碍）。

4. 字体：中文霞鹜文楷 + 代码 JetBrains Mono

目标是中文用霞鹜文楷、代码用 JetBrains Mono。采用混合方案：JetBrains Mono 走 Google Fonts CDN，霞鹜文楷只设 font-family 名走系统回退——用户本地装了才显示，省去几 MB webfont 的网络开销。

Stack 主题的字体由三个 CSS 变量控制（在 variables.scss）：--base-font-family（界面）、--article-font-family（正文，继承 base）、--code-font-family（代码）。覆盖方式：

layouts/_partials/head/custom-font.html：把加载的 Google Fonts 从 Lato 换成 JetBrains Mono
assets/scss/custom.scss：重定义三个 CSS 变量

1
2
3
4
5
6
7


:root {
 --base-font-family: "LXGW WenKai Screen", "LXGW WenKai", "霞鹜文楷",
 -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif;
 --article-font-family: var(--base-font-family);
 --code-font-family: "JetBrains Mono", "LXGW WenKai Mono",
 Menlo, Monaco, Consolas, monospace;
}

生效原理：style.scss 里 @import "custom.scss" 在 variables.scss 之后，我的 :root 重定义排在主题默认值之后，CSS 变量后者覆盖前者。霞鹜文楷回退链：LXGW WenKai Screen → LXGW WenKai → 霞鹜文楷 → 系统无衬线，未装则回退 PingFang SC / 微软雅黑。

踩坑：custom.scss 是静态资源，不经过 Hugo 模板引擎，只能用 CSS 注释，不能写 {{}}（否则 SCSS 编译报错）。

5. 评论系统 Giscus + 社交链接

评论选 Giscus（基于 GitHub Discussions，与 GitHub Pages 技术栈契合，免费无广告）。社交在原有 GitHub + RSS 基础上加 CSDN 和 Email。

Giscus 需要 repo-id 和 category-id。这两个不必走 giscus.app 配置页，直接用 GitHub API 取：

1
2
3
4
5
6
7


# 启用 Discussions（REST PATCH）
curl -X PATCH -H "Authorization: token $TOKEN" \
 https://api.github.com/repos/vamViolet/notion-hugo-meme \
 -d '{"has_discussions": true}'

# 取 repo-id 和 category-id（GraphQL）
# query: repository(owner,name){ id, discussionCategories(first:20){ nodes{ id name slug } } }

拿到 repo-id R_kgDOTllGGw、Announcements 分类 id DIC_kwDOTllGG84DDR7I，写入 config [params.comments.giscus]。mapping=title 按标题关联 discussion，文章 URL 变了也不丢评论；lightTheme/darkTheme 跟随博客明暗主题。

关键点：Stack 单篇文章的 comments front matter 字段会覆盖全局 [params.comments.enabled]。所以光开全局不够，还要把 archetype 和现有文章的 comments: false 全改成 true（9 篇批量 sed）。

社交：Stack 侧边栏图标经 helper/icon.html 的 resources.GetMatch "icons/.svg" 解析，主题内置图标没有 email/csdn，于是自己画了 assets/icons/email.svg（Tabler mail 风格）和 assets/icons/csdn.svg，在 [menu.social] 引用。

三、踩坑记录

坑 1：Docker Action 生成文件的权限

某次同步新文章，fix-tags 步骤报 PermissionError: [Errno 13] Permission denied。根因：rxrw/notion-blog 是 Docker action，在容器内以 root 生成 content/zh、static/images 文件，归 root 所有；后续 fix-tags / fix-dates 以 runner 用户运行，写或删这些文件就失败。这个潜在 bug 只有在需要改新文件时才暴露——只读的步骤会蒙混过去，所以前面几次构建一直没发现。

修复：在 notion-blog 步骤之后、cleanup 之前加 chmod -R a+rwX content/zh static/images，一次性放开权限。

坑 2：Notion created_time 不可控，迁移文章日期全变成今天

迁移 9 篇 Gridea 老文章时，Notion Action 用页面 created_time 作为文章 date。但 created_time 是只读系统字段，API 创建时自动设为 now，无法覆盖。结果 2021/2023 的老文章同步后全变成今天的日期，堆在归档页顶部当「最新」。

解法：加自愈 workflow 步骤——scripts/migrated-dates.json（title→原日期映射）+ scripts/fix-migrated-dates.py，每次 sync 在 fix-tags 之后、commit 之前重写匹配文章的 date/lastmod 回原日期。幂等，每次同步都跑，文件已在正确日期则不动。

坑 3：Notion 链接必须是绝对 URL

创建 Notion 页面时，两篇文章 block append 报 Invalid URL for link。排查是源 HTML 里有相对锚点（#fn1 脚注、%E7%9B%AE%E5%BD%95 编码的「目录」TOC 链接）。Notion 的 link 字段只接受绝对 http(s) URL。修复：在转换器 text_seg 里加 valid_url 校验，非法链接保留文字、丢弃 link，避免阻断整批 block 写入。

坑 4：mybatisplus 图片 404

2 张 mybatisplus 图片原图在 vamViolet.github.io/post-images/，Action 的 getImage 把文件存到 static/images/post-images/ 子目录时 os.Create 失败（子目录不存在），回退写出裸路径 /post-images/X.png 导致 404。解法：Hugo 把 static/ 全部映射到站点根，直接把图放到 static/post-images/X.png 即可让 /post-images/X.png 解析。文章 Status=Published 不会再被 Action 覆盖，此补丁持久。

四、验证方法

全程无本地 hugo，靠 CI 验证：改完 push → workflow_dispatch 触发 → 轮询 run 状态 → 成功后 curl 线上页面抓 HTML/CSS 确认元素和变量生效。

1
2
3
4
5
6
7
8


# 触发构建（用 git credential 里的 token，无需 gh CLI）
TOKEN=$(printf "protocol=https\nhost=github.com\n\n" | git credential fill | sed -n "s/^password=//p")
curl -X POST -H "Authorization: token $TOKEN" \
 https://api.github.com/repos/vamViolet/notion-hugo-meme/actions/workflows/notion-blog.yml/dispatches \
 -d '{"ref":"master"}'

# 验证字体变量在编译后 CSS 里（minify 后有两个 :root 定义，后者覆盖前者）
curl https://notion.dongxiaoqi.top/scss/style.min.<hash>.css | grep -o 'JetBrains Mono'

五、最终效果

线上 https://notion.dongxiaoqi.top/ 已确认：

侧边栏头像（Tom & Jerry 指挥家，正方形裁剪不拉伸）
技术 / 关于菜单可正常打开（中文分类页），随笔待文章
页脚版权行末尾跳动的心（红色，1.3s 双跳）
中文霞鹜文楷（系统装了才显示）、代码 JetBrains Mono
文章页 Giscus 评论框（参数齐全，待装 App）、侧边栏 CSDN / Email / GitHub / RSS 四图标

六、遗留事项

Giscus App 待手动安装：https://github.com/apps/giscus → Install → 授权 notion-hugo-meme 仓库，否则评论框报错
Notion token 在对话历史明文出现过，建议轮换并更新 GitHub NOTION_TOKEN secret
随笔分类待补文章，/categories/随笔/ 目前 404

博客主题从 MemE 切换到 Stack 实录

Wed, 12 Aug 2026 12:45:00 +0800

一次完整的话题切换实操记录：从 MemE 换到 hugo-theme-stack，顺带把被钉死的 Hugo 老版本解锁。包含三个真实踩坑和 CI 迭代验证过程。

一、背景

博客原本用 MemE 主题（git submodule，钉在 2022 年的 v5.0.0）。MemE v5.0.0 用了旧版 resources.ToCSS API，与新版 Hugo 不兼容，导致 CI 工作流被迫把 Hugo 钉在 0.112.7——这是个 2023 年的老版本，越来越难维护，新特性也用不了。

目标：换成更现代的主题，并顺带解除旧 Hugo 版本锁。

二、选型

候选了三个主流主题，最终选 hugo-theme-stack：

卡片式文章列表、左侧边栏、原生暗色模式切换
维护活跃，文档完善
要求 Hugo ≥ 0.157.0 extended，正好顺带升级

三、改动清单

1. 替换主题 submodule

移除 MemE，新增 Stack 并锁定到稳定 tag：

1
2
3
4
5


git submodule deinit -f themes/meme
git rm -f themes/meme
rm -rf .git/modules/themes/meme
git submodule add -b master https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack
git -C themes/stack checkout v4.0.3

2. 重写 config.toml

从 1432 行的 MemE 配置精简到约 210 行。关键调整：

theme = "stack"
mainSections = ["zh"]：核心，让首页读 content/zh/（Notion Action 同步目录，不改 Action 也不改清理脚本）
[permalinks] zh = "/p/:slug/"：用 Stack 默认 URL 风格，文章 URL 从 /zh/xxx/ 变 /p/xxx/
[menu] 改成 Stack 的 main + social 格式
删除 MemE 专属的 [params]、[outputFormats]、[outputs] 等几百行

3. 重写 archetypes/notion.md

Notion Action 同步时套这个模板。改成 Stack 的 front matter 字段，两个关键点：

draft: false：Stack 默认 archetype 是 draft: true，不显式改 false 的话同步出的文章会被当草稿隐藏
category → categories（复数）：Stack 模板用 .Params.categories 判断分类，单数 key 不会显示分类徽章

4. 升级 Hugo

工作流里 0.112.7 → 0.163.3，extended: true 保留。

四、踩坑记录

整个过程走了三轮 CI 迭代，每个坑都是一次失败构建。

坑 1：计划里的 Hugo 0.157.2 根本不存在

第一轮按计划填 hugo-version: '0.157.2'，peaceiris/actions-hugo 直接报错：

1

Unable to find a compatible Hugo release asset for this runner.

查 Hugo releases 才发现：0.157 线只有 0.157.0，之后直接跳到 0.160+，根本不存在 0.157.1/0.157.2。改成实际存在的 0.163.3（成熟 .3 补丁版本，远高于 Stack 的 min 0.157.0）解决。

教训：版本号要查 releases 确认存在，别想当然填补丁号。

坑 2：菜单图标不在 Stack 内置集

第二轮 Hugo 装上了，但构建报：

1
2


ERROR Error: icon 'code.svg' is not found under 'assets/icons' folder
ERROR Error: icon 'notes.svg' is not found under 'assets/icons' folder

菜单里 技术 用了 icon = "code"、随笔 用了 icon = "notes"，但 Stack 只内置 24 个 SVG（themes/stack/assets/icons/），不含 code/notes。改成内置图标：技术→categories、随笔→archives、关于→user。

教训：主题里引用的资源（图标、图片）要先确认主题是否自带，没有就得自己往 assets/ 放。

坑 3：languageCode 弃用警告

第三轮构建成功，但有 WARN：

1

WARN deprecated: project config key languageCode was deprecated in Hugo v0.158.0

修这个又踩了一层：顶层 languageCode 在 0.158 弃用，移到 [languages.zh].languageCode 后，0.163 又把这个键改名为 locale（连同 languageName → label）。最终用最新键名：

1
2
3
4
5


[languages]
 [languages.zh]
 locale = "zh-CN"
 label = "中文"
 weight = 1

额外风险：显式加 [languages.zh] 后，Hugo 可能把 content/zh/ 当成 zh 语言根目录（而非 section），导致 mainSections=["zh"] 失配、首页变空。本地用下载的 hugo 二进制构建验证过：仍是 section，首页 2 篇文章、/p/ URL 都没变，才敢推 CI。

五、验证方法

这次没用本地 hugo server 预览，直接靠 CI 验证：

git push 后用 GitHub API 手动触发 workflow_dispatch
轮询 run 状态到 completed
失败就下载日志 zip，定位报错步骤，修复重推
成功后抓线上首页 HTML，核对 Stack 标记、文章链接、CSS/JS 资源是否 200

三轮迭代，每轮约 2–3 分钟，比反复起本地服务更快也更接近真实部署环境。

六、最终效果

线上 https://notion.dongxiaoqi.top/ 已确认：

Stack 外观：左侧边栏、卡片式文章列表、暗色模式切换
首页正常显示 2 篇文章，URL 是 /p/xxx/
文章页正文、标题、代码块、标签、阅读时长都正常
/tags/ 三个标签（Hugo / Notion / GitHub-Pages）正常
CSS（55KB）/ JS（8KB）资源都 200，无样式崩坏
旧 /zh/xxx/ URL 已 404（符合预期，文章少无外链，可接受）

七、语言切换器的实现

主题切换上线后，照着 demo 站（demo.stack.cai.im）加了侧边栏的语言切换下拉框。这一节记录实现机制和一个非标准目录结构下踩的坑。

机制：hugo.IsMultilingual

Stack 的切换器在 themes/stack/layouts/_partials/sidebar/left.html，是一个