2026-10-05
维护记录
完成的工作
- 删除博客底部右侧的
powered by hugo与hugo-paper两个外链，保留左侧© {{ 年份 }} {{ 站点标题 }}版权段 ✅- 新增覆写文件
layouts/partials/footer.html，照搬 vendor 主题themes/hugo-paper/layouts/partials/footer.html的结构，仅去掉右侧两个<a>标签 - 顶部加注释说明：与
themes/hugo-paper/layouts/partials/footer.html同步、只尾部两个<a>不同，下次主题 bump 时按此对比 diff - 走覆写模式（与
partials/bg.html/partials/header.html/_default/baseof.html同套路），vendor-in 的themes/hugo-paper/不动，避免下次 sync hugo-paper 时冲突
- 新增覆写文件
- 验证
hugo --minify通过（265 页）、deno task test通过（23/23）、deno task validate-posts通过 - 构建产物
public/中新生成的页面 footer 正确收敛为：1<footer 2 class="mx-auto flex h-[4.5rem] max-w-(--w) items-center px-8 text-xs tracking-wider uppercase opacity-60" 3> 4 <div class="mr-auto">© 2026, sdttttt</div> 5</footer>
遇到的问题
- 调试时
which deno找不到 —— 本机 mise 装了deno 2.9.7但 cwd 不在用 deno 的项目根，shell 没自动激活。直接用绝对路径~/.local/share/mise/installs/deno/2.9.7/bin/deno跑即可 ⚠️ - 下次可直接mise exec -- deno task test public/里能看到一些旧 slug 文件（20240615-immortalwrt的编译踩坑-vc6/、20200402-只需要服务中心-b4y/等）渲染成 PaperMod 风格 footer —— 这是上一次部署留下的旧产物（rename-posts.ts每次重生成随机 4 位 hash），新构建会用新 slugt2s/6v0，CI 下次 deploy 整树覆盖后即消失
下次建议
- vendor-in 主题 + override 模式现已稳定（4 个覆写：
_default/baseof.html、partials/bg.html、partials/header.html、partials/footer.html），下次 sync hugo-paper 时记得逐一对照 diff - 如未来想完全自定义 footer 文案（比如加 RSS / ICP 备案号），直接改
layouts/partials/footer.html即可；版权段目前读site.Copyright，未配置所以走默认© {{ now.Year }} {{ site.Title }}
维护记录（续）
完成的工作
- 清理
static/bg/下的 3 张 JPG（原图为抠图前的备份，按 claudelog 14 续计划"如果不再需要回滚可手动删除"）✅- 删除：
F_tZfZBbwAALItU.jpg(256KB) +FxC7q1YaUAE8SOL.jpg(197KB) +GiG69PDa8AAvoeS.jpg(127KB)，共 ~580KB - 模板
layouts/partials/bg.html没做 basename 去重，同名 JPG/PNG 会被全部加载，所以这次清理同时节省仓库体积和访客下载量 hugo --minify重新构建，public/index.html现在只有 3 个.page-bg__imgdiv（之前是 6 个，jpg+png 各一份）
- 删除：
- 顺手验证：仓库内其它位置无
.jpg引用；.DS_Store在.gitignore里
遇到的问题
- claudelog 14 续写过 “按 basename 优先 PNG、忽略同名 JPG” 的 baseof 重构，但读
layouts/partials/bg.html实际没有这个过滤逻辑（readDir直接 append 所有 jpg/png）⚠️ - 当时要么 claudelog 描述超前于代码改动，要么被回滚过 - 这次没去补这个去重逻辑 —— 因为直接删 JPG 已经解决了"多倍加载"问题（一个 div 一份 URL）；如果以后再加新图，要么用纯 PNG，要么重新审视这个模板
下次建议
- 当前
static/bg/留下.DS_Store（gitignored，不会进仓库），3 张 PNG 各 ~200KB。如果以后想再瘦身，可以用sharp/oxipng对 PNG 做无损压缩，预计能再省 20-30% - claudelog 14 续描述的 baseof 重构可能从未落地；如果未来想严格按"按 basename 去重"的语义加回来，注意当前"删 JPG"已经让模板自然只剩 3 张图，加上去重后行为不变
维护记录（再续）
完成的工作
- 修复
layouts/partials/bg.html模板的后缀白名单- 根因：Go template 第 27 行用
(in (slice ".jpg" ".jpeg" ".png" ".webp" ".gif" ".svg") (path.Ext .Name))，把 JPG/PNG 都接受，static/bg/ 里同名.jpg/.png都会被加入$bgImages，最终页面同时下载 2 倍体积 - 修复：改为
(eq (path.Ext .Name) ".png")，只接受.png后缀 - 位置：
layouts/partials/bg.html:27（readDir 分支） - 防御性收益：以后误传 JPG 到
static/bg/也不会被加载 hugo --minify重建验证：仍是 3 张 png，渲染正确
- 根因：Go template 第 27 行用
遇到的问题
- claudelog 14 续里的描述是"按 basename 优先 PNG、忽略同名 JPG"，但代码里没体现。这次不按"basename 去重"的方案做（更复杂），而是直接把白名单收敛到
.png—— 因为 static/bg/ 事实只使用 PNG，白名单语义最清晰；要支持别的格式再去改也方便 ⚠️
下次建议
- 如果以后真的需要支持多种格式（webp/svg/jpg），可以加一个 helper：
basename → format priority，既保留多格式又避免双倍加载
维护记录（三续）
完成的工作
AGENTS.md「提交与 PR 规范」节追加一条规范：推送前必须先检查远端是否有新提交 ✅- 触发原因：今天这次 push 遇到了 rebase 冲突 + 需要
--force-with-lease才能推上去 —— 根因是本地 commit876248f完成后 CI bot 又推了b71c015 chore(format): prettier markdown，远端在我推上之前已经领先一步 - 新规范内容：
- 推送前必跑：
git fetch origin && git log HEAD..origin/master --oneline - 看到新提交（常见来源：CI bot 的
chore(format)格式化了你刚改的 markdown）必须先 rebase / merge 解决冲突再 push - 避免与远端历史分叉；
--force-with-lease仍是 rebase 后的合规选项，但能避免就避免
- 推送前必跑：
- 触发原因：今天这次 push 遇到了 rebase 冲突 + 需要
下次建议
- 如果 CI race 频繁发生（如 deploy.yml 的
Commit auto-fix results步骤在 push 完成后又产生新 commit），可以考虑：- 给 auto-fix 脚本加
git fetch < origin --quiet && git rev-parse HEAD检查：如果本地 HEAD 跟 fetch 后的 origin/master HEAD 不一致，说明已有人推送，则跳过 auto-fix commit - 或者把
Commit auto-fix results步骤拆到 deploy job 之后单独跑，避免跟用户 push 抢顺序
- 给 auto-fix 脚本加
- 当前
git-commit-push.ts的pull --rebase已经会捕获到远端领先，但没有"在 add -A 之前先 fetch 检查"的逻辑 —— 如果有上游 race 担忧，可以在脚本里加一步 dry-rungit fetch+ 比比HEAD与origin/master，有差异时先 dry-run 报错而不是直接 add + commit
维护记录（四续）
完成的工作
- 主题架构重构：layouts/ override → themes/sdttttt-paper/ 子主题（从方案 A/B/C 中选 C）✅
- 背景：此前用
layouts/覆写 + vendor-inthemes/hugo-paper/两层结构，维护时需要同步跟踪两个目录；想统一到"自己的主题" - 新结构：
themes/hugo-paper/— 父主题，原样 vendor-inthemes/sdttttt-paper/— 子主题，通过 Hugo[parent] name = "Paper"继承父主题，5 个 override 文件 + 1 个theme.toml+ 1 个README.mdgo.mod— 新增，Hugo modules 入口（module github.com/sdttttt/sdttttt.github.io）hugo.toml—theme = "sdttttt-paper"+ 新增[module.imports]块让父主题作为 module 加载- 旧的
layouts/_default/baseof.html/layouts/partials/{bg,header,footer}.html/assets/custom.css全部git mv到themes/sdttttt-paper/（git 识别为 R，保留 blame）
- 每个 override 文件头注释已更新：明确说明这是 sdttttt-paper 的文件、原件在父主题哪、sync 上游时如何 reapply diff
themes/sdttttt-paper/README.md新建：说明基于什么、override 清单、同步上游两步指南- 删除空的
layouts/和assets/目录（里头仅.DS_Store，已被 .gitignore） - AGENTS.md「项目结构」节 同步重写：描述新两层主题布局、go.mod 入口、主题同步两步走
- 背景：此前用
遇到的问题
[parent]block 在 directory-based 主题下不生效：起初sdttttt-paper/theme.toml写了[parent] name = "hugo-paper"（按目录名猜），但 [parent] 在 Hugo directory-based 加载路径下完全被忽略——构建结果只有 14 页（仅 sdttttt-paper 自带那 4 个 layout 有效页面），其余页面 fallback 到 0 layout，3 个 WARN（taxonomy / term / search 没 layout）⚠️[parent] name实际匹配的是父主题 theme.toml 的name字段而不是目录名：父主题themes/hugo-paper/theme.toml里是name = "Paper"，不是hugo-paper。改成[parent] name = "Paper"后仍然不行——说明 [parent] 这个字段本身在 directory-based 加载路径里就是失效的- 主题继承要求 Hugo modules，不允许 directory-based 加载：查 Hugo 文档后发现
theme = "X"是 directory-based 加载、不参与组件继承；要让 sdttttt-paper override hugo-paper 的 layout，必须双方都作为 module 加载 - Hugo modules 加载
themes/hugo-paper的 path 写法踩坑：path = "themes/hugo-paper"→ Hugo 拼成themes/themes/hugo-paper（错）path = "./themes/hugo-paper"→ 同上（错）path = "hugo-paper"→ ✅ Hugo 按短名从 themesDir 找，识别为 module- 实际成功的配置：
1[[module.imports]] 2 path = "sdttttt-paper" 3[[module.imports]] 4 path = "hugo-paper"
- 构建验证：266 页 / 测试 23/23 / validate-posts 通过；footer / bg / 默认亮色 三个 override 都正确生效
下次建议
- go.mod 与 Hugo modules 体系的引入是这次迁移的最大认知成本。AGENTS.md 已说明 go.mod 是 Hugo modules 入口、不是真的依赖 Go 工具链，但要小心 CI 上 Hugo 版本是否 >= 0.93（项目锁在 0.161.1，无问题）
- 以后 sync 上游 hugo-paper 时会面临两层 diff：父主题
themes/hugo-paper/直接 patch；子主题themes/sdttttt-paper/的 override 文件按每个文件头注释的指引 reapply diff。建议在 sync 前先git diff themes/hugo-paper/ /tmp/hp-clone/看清楚上游改动面再动手 - 可以考虑：在 sync 上游脚本（未来如果有）中自动检查
themes/sdttttt-paper/的每个 override 文件是否需要重同步——比如基于 “diff themes/hugo-paper/X vs /tmp/hp-clone/X，如果上游 X 有变且 sdttttt-paper 也存在同名 override，则报警” - 后续可能简化：如果 sync 上游的成本大于 override 的价值（override 变化频繁），可以考虑拆分成多个更小的子主题（一个子主题负责一个 override 关注点），但现在 4 个 override 不复杂，没必要拆