blackwolf/AGENTS.md

AGENTS.md

黑狼小站：Hugo + hugo-PaperMod 博客，用 Quarto 渲染少量 .qmd。 站点地址 https://blackwolf.drwater.net/ ，文章以中文为主。

构建与发布

• make render：渲染内容并构建站点，产物在 blackwolf/（已 gitignore）。
• make：等价于 render + update（rsync 到 dwuser@drwater.net:/home/www/blackwolf/）+ git（add . / commit -m compile / push）。
• Hugo 缓存默认指到 $(TMPDIR)hugo-cache，避免 ~/Library/Caches 不可写。可用 HUGO_CACHEDIR=... make render 覆盖。
• Quarto 是可选依赖：render 依次尝试 quarto CLI、R 的 quarto 包，都没有时跳过渲染并提示，直接用已提交的 .md。需要渲染 .qmd 时再 brew install --cask quarto。
• themes/、blackwolf/ 均为本地/生成目录，不入库；themes/hugo-PaperMod 是主题的本地 clone。

改完内容至少要跑一次 make render 确认能出站（72 页上下，正常应退出码 0）。

目录约定

• content/article/：随笔、作文，站内「记录点滴」栏目。
• content/note/：学习笔记（「学习笔记」）。
• content/math/：数学（「数学大爆炸」）。
• content/music/：音乐（「音符律动」），多为一篇一目录，含媒体文件。
• content/aboutme/：关于页，cascade 配置为不渲染、不列目录。
• 顶部菜单、分页、评论等集中在 config.yml。
• assets/、layouts/、i18n/ 覆盖主题默认样式与模板。

新增文章

1. 正文放进对应栏目目录，文件名用 YYYYMMDD-短横线英文标题.md，例如 content/article/20260927-fall-of-my-school.md。

2. front matter 沿用现有写法：

   ---
   title: 一零一的初秋
   author: Black Wolf
   date: 2026-09-27
   slug: fall-of-my-school
   ---
   

3. 需要项：

   • 数学公式：加 math: true（并保持 $...$ / $$...$$ 写法）。
   • 分类/标签：用 categories:、tags:（可加 series:）。
   • 更新引用地址由 config.yml 的 editPost 拼出，无需在正文里写。

4. 跑 make render 验证；如只想本地看效果，HUGO_CACHEDIR=$TMPDIR/hugo-cache hugo server。

注意事项

• .qmd 在 config.yml 的 ignoreFiles 里，Hugo 不会直接构建；实际构建的是同名 .md。 改 .qmd 后必须重新生成 .md（装了 Quarto 时 make render 会自动做），否则站点仍是旧内容。 当前 content/note/KETwords 和 content/math/eulers-remainder-theorem 都有 .qmd + .md 两份。
• 不要手工改 blackwolf/ 下的产物或 resources/_gen/ 缓存；构建会覆盖，且部分缓存文件已被 git 跟踪。
• Hugo v0.168 会对 config.yml 里 languageCode、languageName 报 deprecated 警告，暂不影响构建。
• 提交信息固定为 compile，由 make git 生成；不要另行创建分支或改写历史，除非明确要求。