From d809dc41a998044e02899a98f888b4a1ddfdc91e Mon Sep 17 00:00:00 2001
From: ming <mingsu@rcees.ac.cn>
Date: Fri, 16 Oct 2026 21:51:58 +0800
Subject: [PATCH] compile

---
 AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile  | 18 ++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..284f89e
--- /dev/null
+++ b/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` 生成；不要另行创建分支或改写历史，除非明确要求。
diff --git a/Makefile b/Makefile
index 3e886cb..85f47cc 100644
--- a/Makefile
+++ b/Makefile
@@ -3,9 +3,27 @@
 # 默认目标：执行所有操作
 all: render update git
 
+# 渲染 .qmd 的命令：优先用 quarto CLI，其次用 R 的 quarto 包；
+# 两者都没有时跳过（忽略 .qmd，直接用已提交的 .md）。
+QUARTO ?= $(shell command -v quarto 2>/dev/null)
+ifeq ($(QUARTO),)
+QUARTO_R := $(shell Rscript -e 'if (requireNamespace("quarto", quietly = TRUE)) cat("yes")' 2>/dev/null)
+endif
+
+HUGO_CACHEDIR ?= $(TMPDIR)hugo-cache
+export HUGO_CACHEDIR
+
 # 目标：渲染 Quarto 文件
 render:
+ifeq ($(QUARTO),)
+ifeq ($(QUARTO_R),yes)
 	Rscript -e "quarto::quarto_render()"
+else
+	@echo "warn: quarto 与 R 的 quarto 包均未安装，跳过 .qmd 渲染，直接使用已生成的 .md"
+endif
+else
+	$(QUARTO) render
+endif
 	hugo -d blackwolf
 
 # 目标：更新网站内容