compile

AGENTS.md

@@ -0,0 +1,53 @@
+# 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 沿用现有写法：
+
+   ```yaml
+   ---
+   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` 生成；不要另行创建分支或改写历史，除非明确要求。