GitHub-Pages 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

notion-hugo-meme 操作手册

Wed, 29 Jul 2026 03:05:00 +0800

notion-hugo-meme 操作手册

本项目把 Notion 数据库作为内容源，通过 GitHub Actions 自动同步为 Markdown，再用 Hugo 构建成静态博客并部署到 GitHub Pages。本文档梳理项目结构，并给出从「写文章」到「上线/下线」的完整操作流程。

仓库地址：https://github.com/vamViolet/notion-hugo-meme 博客地址：https://notion.dongxiaoqi.top/

一、整体架构

数据流是单向的、全自动的（每 2 小时触发一次，也可手动触发）：

1
2
3
4
5


Notion 数据库 ──(rxrw/notion-blog Action)──> content/zh/*.md ──(Hugo build)──> GitHub Pages
 │ │
 └─ 把 Status=Finished 的文章拉成 md └─ https://notion.dongxiaoqi.top/
 └─ 同步成功后把 Status 改成 Published
 └─ 清理步骤：删除已下线文章的 md

三个关键角色：

Notion 数据库：唯一的内容编辑入口。每篇文章是一条记录，Status 控制是否上线。
GitHub 仓库：存放 Hugo 站点源码、同步出来的 md、以及自动化工作流。
GitHub Pages：托管构建产物，对外提供博客访问。

二、项目结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


notion-hugo-meme/
├── .github/workflows/notion-blog.yml # 核心：同步 + 清理 + 构建 + 部署 的工作流
├── config.toml # Hugo 站点配置（站名、域名、主题、菜单等）
├── notionblog.config.json # notion-blog Action 的配置（数据库 ID、字段映射、过滤规则）
├── archetypes/
│ ├── default.md # `hugo new` 默认模板
│ └── notion.md # Notion 同步时套用的 front matter 模板
├── content/zh/ # 同步出来的文章 md（按 Category 分子目录）
│ └── 建筑服务能力开发.md
├── static/
│ ├── CNAME # 自定义域名（notion.dongxiaoqi.top）
│ └── images/ # 文章图片（Action 自动下载到这里）
├── themes/meme/ # MemE 主题（git submodule，指向 rxrw/hugo-theme-meme）
├── resources/ # Hugo 构建缓存
└── README.md

关键配置文件

notionblog.config.json —— 决定 Action 怎么从 Notion 拉文章：

字段	含义
`filterProp` / `filterValue`	只同步 `Status` 为 `Finished` 的文章
`publishedValue`	同步成功后把 Status 改成 `Published`
`propertyCategories` / `categoryMap`	`Category` 字段映射：技术→tech、随笔→essay、关于→about，首页→根目录
`contentFolder`	同步到的目录：`content/zh`
`imagesFolder` / `imagesLink`	图片下载到 `static/images/`，链接前缀 `/images`

config.toml —— Hugo 站点配置要点：

baseURL = "https://notion.dongxiaoqi.top/"：自定义域名，构建时不能用 github.io URL 覆盖，否则内链全 404。
title = "dongxiaoqi's Blog"：站点名。
theme = "meme"：使用 MemE 主题（submodule，v5.0.0，2022 年版）。

.github/workflows/notion-blog.yml —— 两个 Job：

auto-sync-from-notion-to-github：checkout → 跑 notion-blog Action 拉文章 → 清理已下线文章 → 提交推送。
build-and-deploy：拉最新提交 → Hugo 0.112.7 extended 构建 → 部署到 GitHub Pages。

三、Notion 数据库字段

每篇文章（一条记录）需要这些属性：

属性	类型	作用
`Status`	状态（status）	控制上线：`Finished`/`Published` = 在线，其余 = 下线
`Category`	单选（select）	分类目录：`首页`/`技术`/`随笔`/`关于`
`Tags`	多选（multi_select）	标签
`Created by`	创建者（created_by）	Action 读取作者名（硬编码依赖，缺了会报错）

Status 状态机

Status	含义	博客上是否可见
`In progress`（进行中）	写到一半	否
`Finished`	写完待发布 → 下次同步会拉取并上线	是（同步后）
`Published`	已上线（同步后 Action 自动置为此状态）	是
`Offline`（已下线）	主动下线 → 清理步骤会删掉对应 md	否

注意：博客是纯静态站点，没有登录鉴权，所以「私密」等价于「下线」——只要 Status 不是 Finished/Published，文章就不会出现在博客上。

四、日常操作

4.1 发布一篇新文章

在 Notion 数据库里 New 一条记录，填好 Name（标题）、Category、Tags。
在正文里写内容（支持 Markdown 风格、代码块、表格、图片）。
把 Status 设为 Finished。
等待下次 workflow 触发（最多 2 小时），或去 GitHub 仓库 Actions 页面手动 Run workflow。
同步成功后，文章出现在博客，Status 自动变成 Published。

4.2 修改已发布文章

直接在 Notion 改正文/标题/分类，保持 Status 为 Finished 或 Published，下次同步会更新对应 md。

想立即触发同步，又不想等 2 小时：GitHub 仓库 → Actions → notion-blog → Run workflow。

4.3 下线一篇文章

把 Status 从 Finished/Published 改成 Offline（或 Todo/In progress）即可。下次 run 的清理步骤会自动 git rm 掉对应 md，文章从博客消失。

4.4 改分类 / 改标题

改分类：在 Notion 改 Category。注意：旧分类目录下的旧 md 不会自动删除，需手动清理或等清理步骤处理（清理是按「当前 Notion 里 Finished/Published 的文章」对账的）。
改标题：会生成新文件名的 md，旧文件名的 md 会成为孤儿，下次清理步骤会自动删除。

五、首次部署 / 排错清单

如果同步或部署出问题，按这个顺序排查：

Notion 数据库是否关联了 Integration：数据库右上角 ... → Connections → 添加你创建的 Integration。没关联会 404。
GitHub Secret 是否正确：仓库 Settings → Secrets and variables → Actions，需有 NOTION_TOKEN（值是 Notion Integration token，ntn_ 开头）。
Notion 字段是否齐全：Name/Status/Category/Created by 必须存在且类型正确，缺了 Action 会报错（但 Action 会吞掉错误、显示成功，要看 Actions 日志才能发现）。
GitHub Pages 源是否设为 Actions：仓库 Settings → Pages → Source 选 GitHub Actions（不是 gh-pages 分支）。
域名/CNAME：static/CNAME 必须是裸域名 notion.dongxiaoqi.top，不能带 http://。
Hugo 版本：工作流固定用 0.112.7 extended。MemE v5.0.0 与新版 Hugo 的 resources.ToCSS 不兼容，不要升到 latest，除非先升主题 submodule。

六、已知限制

Action 只增不删：rxrw/notion-blog 只会新增/更新 md，不会删除。下线靠本仓库自加的清理步骤实现。
正文只取前 100 个 block：Action 不做 block 分页，超长文章（>100 个 Notion block）会被截断。
错误被吞：Action 内部出错只 log.Println 后 exit 0，永远显示「成功」。排查要看 Actions 的完整日志。
属性名硬编码：Action 代码里写死了 Name/Category/Created by 等英文字段名，改不了。
**Tags 渲染缺陷：**rxrw/notion-blog 用 tags : {{.Tags}} 渲染多选标签，Go 切片默认输出 [a b c]（空格分隔无逗号），Hugo 会当成一个名为 “a b c” 的畸形标签。本仓库工作流加了 Fix tags front-matter format 步骤，同步后自动改成逗号分隔 [a, b, c]，博客 /tags/ 页和文章页才能正确显示多个独立标签。
Tag 命名约束：Notion 的 tag 名不要含空格（如用 GitHub-Pages 而非 GitHub Pages）。Action 输出端是空格分隔，含空格的标签名无法无损还原，会被错误拆成多个。中文标签不受影响（如生产力）。

七、相关链接

仓库：https://github.com/vamViolet/notion-hugo-meme
博客：https://notion.dongxiaoqi.top/
主题：https://github.com/rxrw/hugo-theme-meme
Action：https://github.com/rxrw/notion-blog