@jiyeqian/md2pdf 1.5.0 → 1.7.3

package/README.md

@@ -1,7 +1,6 @@
 # md2pdf
 
-把 Markdown 排成**优雅的中文 A4 PDF**：报头大标题、元信息条、精心排过的表格/代码/引用/列表、页脚页码。
-不是 pandoc 的默认样式 —— 是可以直接拿去打印、发给别人看的版式。
+把 Markdown 排成**优雅的中文 A4 PDF**：报头大标题、元信息条、精心排过的表格/代码/引用/列表、页脚页码，还支持数学公式与参考文献。不是 pandoc 的默认样式——是可以直接拿去打印、发给别人看的版式。
 
 **elegant 主题**（默认，墨蓝 + 古铜）：
 
@@ -13,30 +12,13 @@
 
 仓库：https://cnb.cool/jiyeqian/md2pdf
 
-## 两部分:命令 + 说明书
-
-这个工具是两层结构,各自独立存在、各自分发:
-
-| 层 | 是什么 | 给谁用 | 落在哪 |
-| --- | --- | --- | --- |
-| **命令** `md2pdf` | 真正的程序(Node + 无头 Chrome 渲染) | 你、任何脚本 | npm 全局安装到 `node_modules/@jiyeqian/md2pdf/` |
-| **技能说明书** `skill/SKILL.md` | 告诉 Agent「有 `md2pdf` 这个命令、怎么用」 | WorkBuddy 等 Agent 运行时 | `~/.workbuddy/skills/md-to-pdf/` |
-
-npm 的 `postinstall` 一次装两样:环境里有 WorkBuddy(`~/.workbuddy` 存在)就顺带装说明书,
-没有就只装命令。只要命令用 `MD2PDF_SKILL=0` 跳过。
-
-> 为什么说明书不在程序里?因为「怎么用」是给 Agent 看的,「能转换」是给系统跑的 ——
-> 混在一起会让换机器时多一份要同步的实现。说明书只有一份,就在仓库 `skill/`。
-
 ## 安装
 
-**一条命令**（需要 Node ≥ 18，建议 ≥ 22）：
-
 ```bash
-npm install -g @jiyeqian/md2pdf
+npm install -g @jiyeqian/md2pdf   # 需要 Node ≥ 18（建议 ≥ 22）
 ```
 
-它会装上 `md2pdf` 命令；`postinstall` 顺带把技能说明书装进 `~/.workbuddy`（存在时）。
+装上即可用 `md2pdf` 命令；npm 的 `postinstall` 会把技能说明书装进 `~/.workbuddy`（存在时，供 Agent 使用）。
 
 ```bash
 md2pdf 你的文档.md --open   # 装完试一下
@@ -47,26 +29,9 @@ md2pdf 你的文档.md --open   # 装完试一下
 | 变量 | 作用 |
 | --- | --- |
 | `MD2PDF_SKILL=0` | 安装时不装 Agent 技能说明书 |
-| `MD2PDF_SKILL_DIR=<dir>` | 说明书落点，默认 `~/.workbuddy/skills/md-to-pdf`（`~/.workbuddy` 不存在时默认不装） |
-
-### 在仓库里开发
-
-```bash
-git clone https://cnb.cool/jiyeqian/md2pdf.git
-cd md2pdf
-npm link             # 把 bin/md2pdf 软链进 PATH，指向仓库本身，改代码立即生效
-```
+| `MD2PDF_SKILL_DIR=<dir>` | 说明书落点，默认 `~/.workbuddy/skills/md-to-pdf` |
 
-`npm link` 之后命令就是仓库本身，改完立即生效，不需要重装。
-
-### 依赖
-
-| 依赖 | 要求 | 说明 |
-| --- | --- | --- |
-| Node.js | ≥ 18（建议 ≥ 22） | < 22 时自动启用内置 WebSocket 实现；`MD2PDF_NODE` 可指定 |
-| Chrome / Edge / Chromium | 任一 | 只用来渲染，不联网；`MD2PDF_CHROME` 可指定路径 |
-
-零 npm 依赖 —— Markdown 解析器（marked）已内置在 `vendor/`，装好即用。
+**依赖**：Node.js ≥ 18（建议 ≥ 22），以及 Chrome / Edge / Chromium 任一（只渲染、不联网）。零 npm 运行时依赖——`marked` 与 MathJax 已内置在 `vendor/`。
 
 ## 用法
 
@@ -81,23 +46,19 @@ md2pdf 文件名.md --theme minimal --toc
 
 | 选项 | 作用 |
 | --- | --- |
-| `-o, --output <path>` | 输出路径；多文件或目标是目录时，作为输出目录 |
-| `--theme <name>` | `elegant`（默认，墨蓝＋古铜）｜ `minimal`（黑白公文风） |
-| `--title <text>` | 覆盖标题（默认：正文首个 H1 → frontmatter.title → 文件名） |
-| `--kicker <text>` | 报头小标题；`SKILL.md` 默认显示「技能文档」 |
-| `--no-meta` | 不要 frontmatter 元信息条 |
-| `--no-lead` | 首段不作为导语放大 |
-| `-t, --toc` | 文首插入目录页（取自 H2，需 2 个以上），每项可点击跳转 |
-| `--no-outline` | 不生成 PDF 书签（**默认生成**，见下） |
+| `-o, --output <path>` | 输出路径；多文件或目标是目录时作为输出目录 |
+| `--theme <name>` | `elegant`（默认）｜ `minimal` |
+| `--title <text>` / `--kicker <text>` | 覆盖标题 / 报头小标题 |
+| `--no-meta` / `--no-lead` | 不要元信息条 / 首段不作为导语 |
+| `-t, --toc` | 文首插入目录页（取自 H2），条目可点击跳转 |
+| `--no-outline` | 不生成 PDF 书签（默认生成） |
+| `--bibliography [footnote\|bib]` | 将脚注收集为「参考文献」章节（默认 `footnote`；`bib` 为未来支持） |
+| `--numbering <mode>` | 章节编号：`auto`（默认，识别到已有编号则不动）｜ `force`（强制）｜ `none`（不加） |
 | `--link-urls` | 正文链接后附 URL（纸质可读） |
-| `--landscape` | 横向页面 |
-| `--font-size <pt>` | 正文字号，默认 10.5 |
-| `--margin <mm>` | 页边距，默认 20；可写 `"20,18"`（上下,左右） |
-| `--no-footer` | 不要页脚页码 |
-| `--footer-left / --footer-right <text>` | 页脚左右文字 |
-| `--colophon <text>` | 文末落款（默认：来源文件名） |
-| `--keep-html` | 保留中间 HTML，方便调样式 |
-| `--html-only` | 只生成 HTML，不启动浏览器（调样式 / CI 校验用） |
+| `--landscape` / `--font-size <pt>` / `--margin <mm>` | 横向 / 字号（默认 10.5）/ 页边距（默认 20） |
+| `--no-footer` / `--footer-left` / `--footer-right` | 页脚控制 |
+| `--colophon <text>` | 文末落款 |
+| `--keep-html` / `--html-only` | 留中间 HTML 调样式 / 只出 HTML（CI 校验用） |
 | `--open` | 完成后打开 PDF |
 
 布尔选项支持 `--flag=false`。环境变量：`MD2PDF_CHROME`、`MD2PDF_NODE`、`MD2PDF_WS=mini`。
@@ -106,17 +67,10 @@ md2pdf 文件名.md --theme minimal --toc
 
 | | 是什么 | 在哪看 | 怎么开 |
 | --- | --- | --- | --- |
-| **目录页** | 排在文首的一张目录，条目是**可点击的内链** | 文档第 1 页 | `-t / --toc`（默认关） |
-| **PDF 书签** | PDF 阅读器侧边栏里的**章节大纲树**（可折叠、点击跳转） | 阅读器侧栏 | **默认开**，`--no-outline` 关 |
+| **目录页** | 文首一张目录，条目是**可点击内链** | 文档第 1 页 | `-t / --toc`（默认关） |
+| **PDF 书签** | 阅读器侧栏的**章节大纲树** | 阅读器侧栏 | **默认开**，`--no-outline` 关 |
 
-书签由 Chrome 按 HTML 的 `h1`–`h6` 结构生成（报头标题为根，H2/H3 逐层嵌套），
-所以只要文档用了标准标题层级，就有对应的大纲，不需要额外配置。
-
-需要看侧栏的阅读器操作：macOS 预览需手动展开侧栏（**⌘⌥3**，或右上角侧栏按钮）；
-Acrobat / 福昕 / Chrome 内置阅读器点侧栏图标即可。侧栏是否自动展开由阅读器自身决定，
-本工具不写 `/PageMode`（改这个字段要重写 PDF 目录对象，收益不值那份风险）。
-
-自己验一份 PDF 的书签与内链：
+书签由 Chrome 按 `h1`–`h6` 结构生成，无需额外配置。验一份 PDF 的书签与内链：
 
 ```bash
 node ci/inspect-pdf.mjs out.pdf
@@ -124,107 +78,34 @@ node ci/inspect-pdf.mjs out.pdf
 
 ## 排版规则
 
-- 首个 H1 提升为报头大标题，正文不再重复；其后的首段自动成为导语。
-- YAML frontmatter 的 `name` / `description` 生成元信息条；description 里「适用于…」「不用于…」会自动拆成「适用 / 不适用」两栏。
-- H2 自动分节并加色块标记；表格深色表头＋隔行浅底；有序列表用圆形序号。
-- 数学公式：正文里的 `$...$`（行内）与 `$$...$$`（独立成行）由内置 MathJax 渲染（SVG 输出，零字体依赖）。
-- 相对路径图片自动解析成绝对地址，能正常进入 PDF。
-
-## 改样式
+- 首个 H1 提升为报头大标题；其后的首段自动成为导语。
+- YAML frontmatter 的 `name` / `description` 生成元信息条；「适用于…/不用于…」自动拆两栏。
+- H2 自动分节加色块；表格深色表头＋隔行浅底；有序列表圆形序号。
+- 数学公式：`$...$`（行内）与 `$$...$$`（独立成行）由内置 MathJax 渲染。
+- 脚注：`[^id]` 引用 + `[^id]: 内容` 定义；BibTeX 脚注（`@article{...}` 等）按 GB/T 7714-2025 著录，`--bibliography` 收集为「参考文献」章节。
+- 相对路径图片自动解析进 PDF。
 
-```
-assets/base.css              骨架（占位符 {{PAGE_SIZE}} {{MARGIN_*}} {{FONT_SIZE}}）
-assets/theme-elegant.css     墨蓝 + 古铜（默认）
-assets/theme-minimal.css     黑白公文
-assets/shell.html            页面骨架
-```
-
-改完直接重跑命令，不用重启任何东西。
+改样式：`assets/base.css`（骨架）与 `assets/theme-*.css`（配色），改完重跑命令即生效。
 
-## 它是怎么工作的
-
-```
-Markdown ──(marked)──▶ HTML ──(模板+主题 CSS)──▶ 完整 HTML
-        ──▶ 无头 Chrome（CDP Page.printToPDF）──▶ PDF
-```
-
-选 CDP 而不是 `chrome --print-to-pdf` 的原因：命令行版不支持页眉页脚模板，出不了页码。
-`preferCSSPageSize: true` 让页面尺寸/边距完全由 CSS `@page` 控制。
-
-## 校验与 CI
-
-```bash
-bash ci/validate.sh        # 本地跑，和 CI 完全同一套检查（约几秒）
-```
-
-校验分四层，全部不需要浏览器：
-
-1. **结构**：必需文件齐全、`bin/` 与安装脚本有可执行位、关键文件确实被 git 跟踪
-2. **语法**：`sh -n`、`node --check`
-3. **一致性**：版本号（package.json ↔ src）；模板占位符 ↔ 替换逻辑双向闭合；
-   主题 CSS 里 `var(--x)` 全部有定义；占位符替换必须是全量的
-4. **行为**：`--help`/`--version` 冒烟；`examples/demo.md` 端到端渲染到 HTML，
-   断言表格、代码块、引用、嵌套列表、目录、链接 URL、分节都在，且无占位符残留
-   与 `undefined` 泄漏；目录锚点与标题 `id` 一一对应
-5. **接线**：PDF 书签这类"只存在于 PDF 里"的特性，CI 没有浏览器验不了结果，
-   就退一步断言参数真的传进了 `printToPDF`、开关真的从 `main` 接到了渲染 ——
-   光有 `case '--no-outline'` 不等于接到了
-
-最后还有一步**守卫自测**：故意破坏一份副本（塞入未定义的占位符、改错主题变量名、
-改乱版本号、把目录项退回纯文本、关掉书签参数…），断言校验确实会失败 ——
-只会"全绿"的校验等于没有校验。
-
-CNB 云原生构建在 push / PR 时跑同一脚本；打 tag 时发布到 npm
-（见 `.cnb.yml`）。
-
-### 发版
-
-改完 `src/md2pdf.mjs` 的 `VERSION` 与 `package.json` 的 `version`（校验会检查两者一致），然后：
+## 开发
 
 ```bash
-git tag v1.4.0 && git push origin v1.4.0
-```
-
-流水线会自动：校验 → `npm publish --access public`（发布到 npm，需在 CNB 项目里配置 `NPM_TOKEN` secret）。
-也可以本地手动 `npm publish`。
-
-注意 CNB **不允许删除 tag**，打错了只能升版本号再发一版。
-
-## 目录结构
-
-```
-bin/md2pdf              启动器（解析软链、挑选 node）
-src/md2pdf.mjs          主程序
-src/ws.mjs              Node < 22 时的极简 WebSocket 客户端
-src/install-skill.mjs   npm postinstall：把技能说明书装进 WorkBuddy
-assets/                 样式与页面骨架
-vendor/marked.esm.js    内置 Markdown 解析器
-examples/demo.md        示例文档（含表格/代码/引用/嵌套列表）
-ci/validate.sh          校验入口（本地与 CI 同一套）
-ci/checks.mjs           一致性 + 端到端渲染断言
-ci/inspect-pdf.mjs      读出 PDF 的书签树与链接注解（本地验证 outline 用）
-skill/SKILL.md          Agent 技能说明书（postinstall 会装到技能目录）
+git clone https://cnb.cool/jiyeqian/md2pdf.git
+cd md2pdf
+npm link              # 命令指向仓库，改代码立即生效
+bash ci/validate.sh   # 本地与 CI 同一套校验（无需浏览器）
 ```
 
-
+发版：同步 `src/md2pdf.mjs` 的 `VERSION` 与 `package.json` 的 `version`，然后 `git tag v1.x.x && git push origin v1.x.x`，CNB 流水线会自动 `npm publish`（需配置 `NPM_TOKEN`）。
 
 ## 常见问题
 
-**装到哪了 / 怎么升级** → npm 全局包在 `npm root -g` 下的 `@jiyeqian/md2pdf`，命令软链进 npm 的 bin 目录。
-升级：`npm update -g @jiyeqian/md2pdf`。
-
-**npm 装不上** → 确认 npm registry 可达；也可以 clone 仓库后 `npm link` 本地开发。
+**找不到 Chrome** → `export MD2PDF_CHROME=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome`
 
-**找不到 Chrome** → 设 `export MD2PDF_CHROME=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome`
+**Node 版本老** → 升级到 22+；不升也能用（自动走内置 WebSocket）。
 
-**Node 版本老** → 升级到 22+；不想升也能用（自动走内置 WebSocket），只是没在老版本上充分测试。
-
-**PDF 里目录不能点击** → Chrome 打印不保留内部锚点跳转，目录是纯文本。
-
-**想改默认字号/边距** → 直接改命令行参数；要永久生效就改 `src/md2pdf.mjs` 里 `parseArgs` 的默认值。
+**想改默认字号/边距** → 改命令行参数；永久生效改 `src/md2pdf.mjs` 里 `parseArgs` 的默认值。
 
 ## License
 
-MIT
-
-第三方组件：`vendor/marked.esm.js` 来自 [marked](https://github.com/markedjs/marked)（MIT License）；`vendor/mathjax/tex-svg.js` 来自 [MathJax](https://github.com/mathjax/MathJax)（Apache-2.0 License）。均随仓库分发以便零依赖安装。
+MIT。第三方组件：`vendor/marked.esm.js`（marked，MIT）、`vendor/mathjax/tex-svg.js`（MathJax，Apache-2.0），均随仓库分发以便零依赖安装。

package/assets/base.css

@@ -208,6 +208,20 @@ hr {
 }
 img { max-width: 100%; height: auto; display: block; margin: 8px auto 14px; }
 
+/* ---------- 脚注与参考文献 ---------- */
+sup.fnref { font-size: .7em; line-height: 0; }
+sup.fnref a { border-bottom: none; color: var(--accent); }
+a.fnref-back { border-bottom: none; color: var(--accent); font-weight: 600; }
+.references, .footnotes {
+  list-style: none; counter-reset: none;
+  margin: 4px 0 0; padding-left: 0;
+}
+.references li, .footnotes li {
+  position: relative; margin: 0 0 8px; padding-left: 0;
+  font-size: .9em; line-height: 1.75; text-align: left;
+}
+.references li::before, .footnotes li::before { content: none; }
+
 /* ---------- 文末 ---------- */
 .colophon {
   margin-top: 32px; padding-top: 12px; border-top: 1px solid var(--rule);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiyeqian/md2pdf",
-  "version": "1.5.0",
+  "version": "1.7.3",
   "description": "把 Markdown 排成优雅的中文 A4 PDF（无头 Chrome 渲染，带报头、表格/代码排版与页脚页码）",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -47,6 +47,8 @@ npm install -g @jiyeqian/md2pdf
 | `--no-meta` / `--no-lead` | 去掉元信息条 / 首段不作为导语 |
 | `-t, --toc` | 文首插入目录页（取自 H2），条目可点击跳转 |
 | `--no-outline` | 不生成 PDF 书签（默认生成） |
+| `--bibliography [footnote\|bib]` | 将脚注收集为「参考文献」章节（默认 footnote；bib 为未来支持） |
+| `--numbering <mode>` | 章节编号：auto（默认）｜ force（强制）｜ none（不加） |
 | `--link-urls` | 链接后附 URL |
 | `--landscape` / `--font-size` / `--margin` | 横向 / 字号（默认 10.5pt）/ 页边距（默认 20mm） |
 | `--no-footer` / `--footer-left` / `--footer-right` | 页脚控制 |

package/src/md2pdf.mjs

@@ -40,7 +40,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const ASSETS = path.join(ROOT, 'assets');
 
-const VERSION = '1.5.0';
+const VERSION = '1.7.3';
 
 // Node ≥ 22 有全局 WebSocket；更老的版本退回到内置的极简实现
 let _WS;
@@ -68,6 +68,8 @@ md2pdf ${VERSION} —— Markdown → 优雅 PDF
       --no-lead            首段不作为导语
   -t, --toc                在文首插入目录页（取自二级标题，可点击跳转）
       --no-outline         不生成 PDF 书签（默认生成，阅读器侧边栏按标题成树）
+      --bibliography [footnote|bib]  将脚注收集为「参考文献」章节（默认 footnote；bib 为未来支持）
+      --numbering <mode>    章节编号：auto（默认，识别到已有编号则不动）| force（强制）| none（不加）
       --link-urls          正文链接后附 URL
       --landscape          横向
       --font-size <pt>     正文字号（默认 10.5）
@@ -107,7 +109,8 @@ function parseArgs(argv) {
     inputs: [], theme: 'elegant', fontSize: 10.5,
     marginTop: 20, marginSide: 18, marginBottom: 18,
     footer: true, footerLeft: '', footerRight: '',
-    meta: true, lead: true, toc: false, linkUrls: false, outline: true,
+    meta: true, lead: true, toc: false, linkUrls: false, outline: true, bibliography: false,
+    numbering: 'auto',
     landscape: false, keepHtml: false, htmlOnly: false, open: false, help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -142,6 +145,14 @@ function parseArgs(argv) {
       case '--no-toc': o.toc = false; break;
       case '--outline': o.outline = true; break;
       case '--no-outline': o.outline = false; break;
+      case '--bibliography': {
+        const n = argv[i + 1];
+        if (n && ['footnote', 'bib'].includes(n)) { o.bibliography = n; i++; }
+        else o.bibliography = 'footnote';
+        break;
+      }
+      case '--numbering': o.numbering = next(); break;
+      case '--no-bibliography': o.bibliography = false; break;
       case '--no-landscape': o.landscape = false; break;
       case '--no-link-urls': o.linkUrls = false; break;
       case '--no-keep-html': o.keepHtml = false; break;
@@ -208,6 +219,190 @@ function sectionize(html) {
     .join('\n');
 }
 
+/* ---------------- 章节编号 ---------------- */
+
+// 标题编号前缀识别（阿拉伯/中文/罗马数字、第X章、括号编号等）
+const HEADING_NUM_RE = /^\s*(?:\d+(?:\.\d+)*[、．.)]\s?|[一二三四五六七八九十百]+[、．.]|第[一二三四五六七八九十百\d]+[章节篇]|\([一二三四五六七八九十\d]+\)|[IVX]+[.、])\s*/;
+
+// 章节编号：mode 为 auto（默认，识别到已有编号则不动）/ force（强制编号）/ none（不动）
+function numberHeadings(html, mode) {
+  if (mode === 'none') return html;
+  const re = /<h([2-6])([^>]*)>([\s\S]*?)<\/h\1>/g;
+  const all = [...html.matchAll(re)];
+  if (!all.length) return html;
+  if (mode !== 'force' && all.some(m => HEADING_NUM_RE.test(stripTags(m[3])))) return html;
+  const counters = [0, 0, 0, 0, 0];
+  return html.replace(re, (m, level, attrs, inner) => {
+    const lvl = parseInt(level, 10) - 2;
+    counters[lvl]++;
+    for (let k = lvl + 1; k < 5; k++) counters[k] = 0;
+    const num = counters.slice(0, lvl + 1).join('.');
+    return '<h' + level + attrs + '>' + num + ' ' + inner.replace(HEADING_NUM_RE, '') + '</h' + level + '>';
+  });
+}
+
+/* ---------------- 脚注与参考文献 ---------------- */
+
+// 解析 markdown 脚注：[^id]: 定义（后续缩进行为内容）与正文 [^id] 引用
+function parseFootnotes(body) {
+  const footnotes = [];
+  const lines = body.split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\[\^([^\]]+)\]:[ \t]*(.*)$/.exec(lines[i]);
+    if (!m) { out.push(lines[i]); continue; }
+    const id = m[1];
+    let content = m[2];
+    while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1])) {
+      content += '\n' + lines[i + 1].trim();
+      i++;
+    }
+    footnotes.push({ id, content });
+  }
+  return { body: out.join('\n'), footnotes };
+}
+
+// 脚注内容是否为 BibTeX（@type{...}）
+function isBibTeX(content) {
+  return /^\s*@[A-Za-z]+\s*\{/.test(content);
+}
+
+// 解析 BibTeX 条目（支持嵌套花括号、双引号与无引号数值）
+function parseBibTeX(content) {
+  const t = content.trim();
+  const m = /^@([A-Za-z]+)\s*\{\s*([^,]*),\s*([\s\S]*)\}\s*$/.exec(t);
+  if (!m) return null;
+  const type = m[1].toLowerCase();
+  const key = m[2].trim();
+  const body = m[3];
+  const fields = {};
+  let i = 0;
+  const n = body.length;
+  while (i < n) {
+    while (i < n && /[\s,]/.test(body[i])) i++;
+    const nm = /^[A-Za-z][A-Za-z0-9_-]*/.exec(body.slice(i));
+    if (!nm) break;
+    const name = nm[0].toLowerCase();
+    i += nm[0].length;
+    while (i < n && /\s/.test(body[i])) i++;
+    if (body[i] !== '=') break;
+    i++;
+    while (i < n && /\s/.test(body[i])) i++;
+    let value = '';
+    if (body[i] === '{') {
+      let depth = 0, j = i;
+      while (j < n) {
+        if (body[j] === '{') depth++;
+        else if (body[j] === '}') { depth--; if (depth === 0) { j++; break; } }
+        j++;
+      }
+      value = body.slice(i + 1, j - 1);
+      i = j;
+    } else if (body[i] === '"') {
+      const j = body.indexOf('"', i + 1);
+      if (j < 0) break;
+      value = body.slice(i + 1, j);
+      i = j + 1;
+    } else {
+      const vm = /^[^,\s}]+/.exec(body.slice(i));
+      value = vm ? vm[0] : '';
+      i += value.length;
+    }
+    fields[name] = value.trim();
+  }
+  return { type, key, fields };
+}
+
+// 单个作者 → GB/T 7714 姓名格式（中文照写，西文「姓 名缩写.」）
+function formatOneAuthor(a) {
+  const name = a.trim();
+  if (!name) return '';
+  if (/[\u4e00-\u9fa5]/.test(name)) return name;
+  const initials = g => g.split(/\s+/).map(w => (w[0] ? w[0].toUpperCase() + '.' : '')).join('');
+  if (name.includes(',')) {
+    const parts = name.split(',').map(s => s.trim());
+    return parts[1] ? parts[0].toUpperCase() + ' ' + initials(parts[1]) : parts[0].toUpperCase();
+  }
+  const words = name.split(/\s+/);
+  const last = words.pop();
+  return last.toUpperCase() + ' ' + initials(words.join(' '));
+}
+
+// 作者列表 → GB/T 7714（≤3 全列，>3 前 3 + 等/et al.）
+function formatAuthors(authorStr) {
+  if (!authorStr) return '';
+  const authors = authorStr.split(/\s+and\s+/i).map(s => s.trim()).filter(Boolean);
+  if (!authors.length) return '';
+  const isCjk = /[\u4e00-\u9fa5]/.test(authors[0]);
+  if (authors.length <= 3) return authors.map(formatOneAuthor).join(', ');
+  return authors.slice(0, 3).map(formatOneAuthor).join(', ') + (isCjk ? ', 等' : ', et al.');
+}
+
+// BibTeX 条目 → GB/T 7714-2025 著录字符串
+function formatGB7714(entry) {
+  const f = entry.fields;
+  const authors = formatAuthors(f.author);
+  const title = f.title || '';
+  const year = f.year || '';
+  switch (entry.type) {
+    case 'article': {
+      const vol = f.volume || '';
+      const num = f.number || '';
+      const volIssue = vol ? (num ? vol + '(' + num + ')' : vol) : (num ? '(' + num + ')' : '');
+      const pages = f.pages ? ': ' + f.pages : '';
+      let s = (authors ? authors + ' ' : '') + title + '[J]. ' + (f.journal || '') + ', ' + year + (volIssue ? ', ' + volIssue : '') + pages;
+      if (f.doi) s += '. DOI: ' + f.doi;
+      s += '.';
+      return s;
+    }
+    case 'inproceedings':
+    case 'conference': {
+      const pages = f.pages ? ': ' + f.pages : '';
+      return (authors ? authors + ' ' : '') + title + '[C]//' + (f.booktitle || '') + '. ' + (f.address || '') + ', ' + year + pages + '.';
+    }
+    case 'phdthesis':
+    case 'mastersthesis': {
+      return (authors ? authors + ' ' : '') + title + '[D]. ' + (f.address || '') + ': ' + (f.school || '') + ', ' + year + '.';
+    }
+    case 'book': {
+      let s = (authors ? authors + ' ' : '') + title + '[M]. ';
+      if (f.edition) s += f.edition + '. ';
+      const pub = f.address && f.publisher ? f.address + ': ' + f.publisher : (f.address || f.publisher || '');
+      s += pub + (pub ? ', ' : '') + year + '.';
+      return s;
+    }
+    case 'techreport': {
+      return (authors ? authors + ' ' : '') + title + '[R]. ' + (f.institution || '') + ', ' + year + '.';
+    }
+    default: {
+      let s = (authors ? authors + ' ' : '') + title + '[EB/OL]. ';
+      if (f.urldate) s += '(' + f.urldate + ')';
+      if (f.url) s += f.url;
+      s += '.';
+      return s;
+    }
+  }
+}
+
+// 渲染脚注列表；bibliography=true 时作为「参考文献」章节
+function renderFootnotes(footnotes, bibliography, marked) {
+  if (!footnotes.length) return '';
+  const items = footnotes.map((fn, i) => {
+    const num = i + 1;
+    let content;
+    if (isBibTeX(fn.content)) {
+      const entry = parseBibTeX(fn.content);
+      content = entry ? esc(formatGB7714(entry)) : esc(fn.content);
+    } else {
+      content = marked.parseInline(fn.content, { gfm: true });
+    }
+    return '<li id="fn-' + num + '"><a href="#fnref-' + num + '" class="fnref-back">[' + num + ']</a> ' + content + '</li>';
+  }).join('\n');
+  const cls = bibliography ? 'references' : 'footnotes';
+  const list = '<ol class="' + cls + '">\n' + items + '\n</ol>';
+  return '<h2>' + (bibliography ? '参考文献' : '脚注') + '</h2>\n' + list;
+}
+
 /* ---------------- Chrome ---------------- */
 
 function findChrome() {
@@ -338,13 +533,33 @@ class Chrome {
 
 async function renderOne(mdPath, opts, chrome, marked, tmpRoot) {
   const src = await readFile(mdPath, 'utf8');
-  const { fm, body } = splitFrontmatter(src);
+  const { fm, body: rawBody } = splitFrontmatter(src);
   const isSkill = path.basename(mdPath) === 'SKILL.md' || !!fm.name;
 
   // 数学公式：检测 $...$ 或 $...$，命中则注入 MathJax（SVG 输出，零字体依赖）
-  const hasMath = /\$\$|\$[^$\n]+\$/.test(body);
+  const hasMath = /\$\$|\$[^$\n]+\$/.test(rawBody);
+
+  // 脚注：提取 [^id]: 定义，正文 [^id] 引用替换为编号上标
+  const { body, footnotes } = parseFootnotes(rawBody);
+  const fnIndex = new Map();
+  footnotes.forEach((fn, i) => fnIndex.set(fn.id, i + 1));
+  const fnRefCount = new Map();
+  const bodyWithRefs = body.replace(/\[\^([^\]]+)\]/g, (m, id) => {
+    const n = fnIndex.get(id);
+    if (n === undefined) return m;
+    const c = (fnRefCount.get(id) || 0) + 1;
+    fnRefCount.set(id, c);
+    const refId = c === 1 ? 'fnref-' + n : 'fnref-' + n + '-' + c;
+    return '<sup class="fnref" id="' + refId + '"><a href="#fn-' + n + '">[' + n + ']</a></sup>';
+  });
+
+  let html = marked.parse(bodyWithRefs, { gfm: true, breaks: false, async: false });
 
-  let html = marked.parse(body, { gfm: true, breaks: false, async: false });
+  // 脚注/参考文献：先追加到正文末尾，再编号，使参考文献章节纳入编号体系
+  html += renderFootnotes(footnotes, opts.bibliography, marked);
+
+  // 章节编号：H2 起编号，H1 作为文档标题不动
+  html = numberHeadings(html, opts.numbering);
 
   // 标题：正文首个 H1 → 报头
   let title = opts.title || fm.title || '';
@@ -367,8 +582,10 @@ async function renderOne(mdPath, opts, chrome, marked, tmpRoot) {
   }
 
   // 链接 / 图片
-  html = html.replace(/<a\s+href="([^"]*)"([^>]*)>/g, (m, href, rest) =>
-    `<a href="${href}" class="ref"${rest}>`);
+  html = html.replace(/<a\s+href="([^"]*)"([^>]*)>/g, (m, href, rest) => {
+    const cls = /\sclass=/.test(rest) ? '' : ' class="ref"';
+    return `<a href="${href}"${cls}${rest}>`;
+  });
   if (opts.linkUrls) {
     html = html.replace(/<a\s+href="(https?:\/\/[^"]*)"[^>]*>([\s\S]*?)<\/a>/g,
       (m, href, text) => `${m} <span class="link-url">(${esc(href)})</span>`);