# 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` 生成；不要另行创建分支或改写历史，除非明确要求。