@jiyeqian/md2pdf 1.5.0 → 1.6.0

package/README.md

@@ -89,6 +89,7 @@ md2pdf 文件名.md --theme minimal --toc
 | `--no-lead` | 首段不作为导语放大 |
 | `-t, --toc` | 文首插入目录页（取自 H2，需 2 个以上），每项可点击跳转 |
 | `--no-outline` | 不生成 PDF 书签（**默认生成**，见下） |
+| `--bibliography` | 将脚注收集为文末「参考文献」章节（BibTeX 脚注按 GB/T 7714 渲染） |
 | `--link-urls` | 正文链接后附 URL（纸质可读） |
 | `--landscape` | 横向页面 |
 | `--font-size <pt>` | 正文字号，默认 10.5 |
@@ -127,7 +128,139 @@ node ci/inspect-pdf.mjs out.pdf
 - 首个 H1 提升为报头大标题，正文不再重复；其后的首段自动成为导语。
 - YAML frontmatter 的 `name` / `description` 生成元信息条；description 里「适用于…」「不用于…」会自动拆成「适用 / 不适用」两栏。
 - H2 自动分节并加色块标记；表格深色表头＋隔行浅底；有序列表用圆形序号。
-- 数学公式：正文里的 `$...$`（行内）与 `$$...$$`（独立成行）由内置 MathJax 渲染（SVG 输出，零字体依赖）。
+- 数学公式：正文里的 `$...# md2pdf
+
+把 Markdown 排成**优雅的中文 A4 PDF**：报头大标题、元信息条、精心排过的表格/代码/引用/列表、页脚页码。
+不是 pandoc 的默认样式 —— 是可以直接拿去打印、发给别人看的版式。
+
+**elegant 主题**（默认，墨蓝 + 古铜）：
+
+![elegant 主题效果](docs/theme-elegant.png)
+
+**minimal 主题**（黑白公文风）：
+
+![minimal 主题效果](docs/theme-minimal.png)
+
+仓库：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
+```
+
+它会装上 `md2pdf` 命令；`postinstall` 顺带把技能说明书装进 `~/.workbuddy`（存在时）。
+
+```bash
+md2pdf 你的文档.md --open   # 装完试一下
+```
+
+**更新**：`npm update -g @jiyeqian/md2pdf` · **卸载**：`npm uninstall -g @jiyeqian/md2pdf`
+
+| 变量 | 作用 |
+| --- | --- |
+| `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，指向仓库本身，改代码立即生效
+```
+
+`npm link` 之后命令就是仓库本身，改完立即生效，不需要重装。
+
+### 依赖
+
+| 依赖 | 要求 | 说明 |
+| --- | --- | --- |
+| Node.js | ≥ 18（建议 ≥ 22） | < 22 时自动启用内置 WebSocket 实现；`MD2PDF_NODE` 可指定 |
+| Chrome / Edge / Chromium | 任一 | 只用来渲染，不联网；`MD2PDF_CHROME` 可指定路径 |
+
+零 npm 依赖 —— Markdown 解析器（marked）已内置在 `vendor/`，装好即用。
+
+## 用法
+
+```bash
+md2pdf 文件名.md                    # 同目录输出同名 .pdf
+md2pdf 文件名.md --open             # 转完直接打开
+md2pdf a.md b.md -o 输出目录/       # 批量（共用一个浏览器实例，很快）
+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 书签（**默认生成**，见下） |
+| `--bibliography` | 将脚注收集为文末「参考文献」章节（BibTeX 脚注按 GB/T 7714 渲染） |
+| `--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 校验用） |
+| `--open` | 完成后打开 PDF |
+
+布尔选项支持 `--flag=false`。环境变量：`MD2PDF_CHROME`、`MD2PDF_NODE`、`MD2PDF_WS=mini`。
+
+### 目录与书签是两件事
+
+| | 是什么 | 在哪看 | 怎么开 |
+| --- | --- | --- | --- |
+| **目录页** | 排在文首的一张目录，条目是**可点击的内链** | 文档第 1 页 | `-t / --toc`（默认关） |
+| **PDF 书签** | PDF 阅读器侧边栏里的**章节大纲树**（可折叠、点击跳转） | 阅读器侧栏 | **默认开**，`--no-outline` 关 |
+
+书签由 Chrome 按 HTML 的 `h1`–`h6` 结构生成（报头标题为根，H2/H3 逐层嵌套），
+所以只要文档用了标准标题层级，就有对应的大纲，不需要额外配置。
+
+需要看侧栏的阅读器操作：macOS 预览需手动展开侧栏（**⌘⌥3**，或右上角侧栏按钮）；
+Acrobat / 福昕 / Chrome 内置阅读器点侧栏图标即可。侧栏是否自动展开由阅读器自身决定，
+本工具不写 `/PageMode`（改这个字段要重写 PDF 目录对象，收益不值那份风险）。
+
+自己验一份 PDF 的书签与内链：
+
+```bash
+node ci/inspect-pdf.mjs out.pdf
+```
+
+## 排版规则
+
+- 首个 H1 提升为报头大标题，正文不再重复；其后的首段自动成为导语。
+- YAML frontmatter 的 `name` / `description` 生成元信息条；description 里「适用于…」「不用于…」会自动拆成「适用 / 不适用」两栏。
+- H2 自动分节并加色块标记；表格深色表头＋隔行浅底；有序列表用圆形序号。
+（行内）与 `$...$`（独立成行）由内置 MathJax 渲染（SVG 输出，零字体依赖）。
+- 脚注：正文 `[^id]` 引用 + 文末 `[^id]: 内容` 定义；`--bibliography` 时收集为「参考文献」章节。
+- BibTeX 脚注（`@article{...}`、`@book{...}` 等）自动按 GB/T 7714-2025 著录格式渲染。
 - 相对路径图片自动解析成绝对地址，能正常进入 PDF。
 
 ## 改样式

package/assets/base.css

@@ -208,6 +208,19 @@ 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); }
+.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.6.0",
   "description": "把 Markdown 排成优雅的中文 A4 PDF（无头 Chrome 渲染，带报头、表格/代码排版与页脚页码）",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -47,6 +47,7 @@ npm install -g @jiyeqian/md2pdf
 | `--no-meta` / `--no-lead` | 去掉元信息条 / 首段不作为导语 |
 | `-t, --toc` | 文首插入目录页（取自 H2），条目可点击跳转 |
 | `--no-outline` | 不生成 PDF 书签（默认生成） |
+| `--bibliography` | 将脚注收集为「参考文献」章节（BibTeX 脚注按 GB/T 7714 渲染） |
 | `--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.6.0';
 
 // Node ≥ 22 有全局 WebSocket；更老的版本退回到内置的极简实现
 let _WS;
@@ -68,6 +68,7 @@ md2pdf ${VERSION} —— Markdown → 优雅 PDF
       --no-lead            首段不作为导语
   -t, --toc                在文首插入目录页（取自二级标题，可点击跳转）
       --no-outline         不生成 PDF 书签（默认生成，阅读器侧边栏按标题成树）
+      --bibliography       将脚注收集为文末「参考文献」章节（BibTeX 脚注按 GB/T 7714 渲染）
       --link-urls          正文链接后附 URL
       --landscape          横向
       --font-size <pt>     正文字号（默认 10.5）
@@ -107,7 +108,7 @@ 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,
     landscape: false, keepHtml: false, htmlOnly: false, open: false, help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -142,6 +143,8 @@ 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': o.bibliography = true; 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 +211,169 @@ function sectionize(html) {
     .join('\n');
 }
 
+/* ---------------- 脚注与参考文献 ---------------- */
+
+// 解析 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) {
+  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 = esc(fn.content);
+    }
+    return '<li id="fn-' + num + '">[' + num + '] ' + content + '</li>';
+  }).join('\n');
+  const cls = bibliography ? 'references' : 'footnotes';
+  const list = '<ol class="' + cls + '">\n' + items + '\n</ol>';
+  if (bibliography) return '<section><h2 id="sec-refs">参考文献</h2>\n' + list + '</section>';
+  return '<section><h2 id="sec-footnotes">脚注</h2>\n' + list + '</section>';
+}
+
 /* ---------------- Chrome ---------------- */
 
 function findChrome() {
@@ -338,13 +504,22 @@ 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 bodyWithRefs = body.replace(/\[\^([^\]]+)\]/g, (m, id) => {
+    const n = fnIndex.get(id);
+    return n === undefined ? m : '<sup class="fnref"><a href="#fn-' + n + '">[' + n + ']</a></sup>';
+  });
 
-  let html = marked.parse(body, { gfm: true, breaks: false, async: false });
+  let html = marked.parse(bodyWithRefs, { gfm: true, breaks: false, async: false });
 
   // 标题：正文首个 H1 → 报头
   let title = opts.title || fm.title || '';
@@ -402,6 +577,9 @@ async function renderOne(mdPath, opts, chrome, marked, tmpRoot) {
 
   html = sectionize(html);
 
+  // 脚注/参考文献：追加到正文末尾
+  html += renderFootnotes(footnotes, opts.bibliography);
+
   // CSS
   const themeFile = path.join(ASSETS, `theme-${opts.theme}.css`);
   if (!existsSync(themeFile)) throw new Error(`未知主题：${opts.theme}（可用：elegant, minimal）`);