@v1hz/md2docx 2.0.1 → 2.1.0

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">md2docx</h1>
 
 <p align="center">
-  基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。
+  基于 Pandoc 的 Markdown 转 Word 工具。在转换前规范文档结构、补充编号、渲染 Mermaid，并通过可定制的 Word 样式生成 DOCX。
 </p>
 
 <p align="center">
@@ -17,180 +17,339 @@
 
 ## 功能
 
-将 Markdown 转换为格式精美的 Word 文档，自动处理：
+| 功能              | 说明                                                               |
+| ----------------- | ------------------------------------------------------------------ |
+| 文档标题          | 从 YAML frontmatter、H1 或文件名提取标题                           |
+| 标题层级归一化    | 将最浅标题归一化为 H1，并修复标题层级跳跃                          |
+| 标题编号          | 生成 `1`、`1.1`、`1.1.1` 等编号，并可剥离常见的已有中英文编号      |
+| 表格与图片编号    | 自动生成“表 1”“图 1：标题”等题注                                   |
+| Mermaid 图表      | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG   |
+| Word 样式         | 根据 JSON 样式生成 Pandoc reference DOCX，也可从现有 DOCX 提取样式 |
+| Markdown 格式化   | 可只运行预处理流水线，输出格式化后的 Markdown                      |
+| 集中缓存          | 中间文件统一存储到 `~/.md2docx/`，不会在当前目录创建 `tmp/`        |
+| Node 与可执行版本 | 支持 npm CLI，也支持构建不依赖 Node.js/Bun 的平台可执行文件        |
 
-| 功能               | 说明                                                        |
-| ------------------ | ----------------------------------------------------------- |
-| **文档标题**       | 从 frontmatter、H1 或文件名自动提取                         |
-| **标题层级归一化** | 修正标题层级跳跃，确保从 H1 开始连续递增                    |
-| **标题编号**       | 为标题添加多级编号（1、1.1、1.1.1 …），支持剥离已有编号     |
-| **表格编号**       | 自动为表格添加编号（表 1、表 2 …）                          |
-| **图片编号**       | 为独立图片添加编号（图 1、图 2 …）                          |
-| **Mermaid 图表**   | 将 Mermaid 代码块渲染为 PNG 图片                            |
-| **Word 导出**      | 集成 pandoc，传入自定义样式模板，一键生成 .docx             |
-| **样式定制**       | 通过 `config/style.json` 定义文档样式，支持从模板 docx 提取 |
-| **web 配置编辑器** | 浏览器中可视化编辑配置                                      |
+## 安装方式
 
-## 安装
+### npm CLI
 
-**前置依赖**：[Node.js 22.12+](https://nodejs.org) | [Pandoc](https://pandoc.org)
+前置依赖：
+
+- [Node.js 22.12+](https://nodejs.org/)
+- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用
 
 ```bash
 npm install -g @v1hz/md2docx
-md2docx --file docs/example.md
+md2docx --version
+md2docx report.md
 ```
 
-也可通过 `npx @v1hz/md2docx` 直接运行。
+也可以不全局安装：
+
+```bash
+npx @v1hz/md2docx report.md
+```
 
 ## 快速开始
 
 ```bash
-# 转换 Markdown 为 Word
-md2docx --file docs/example.md
+# 只有输入路径时，可以省略 --file
+md2docx report.md
+
+# 使用任何转换选项时，输入必须通过 --file 指定
+md2docx --file report.md --output output/report.docx --force
 
-# 使用自定义配置、样式和输出路径
-md2docx -f docs/example.md -c config.json -s style.json -o output/example.docx
+# 使用自定义配置和样式
+md2docx -f report.md -c config.json -s style.json
 
 # 只执行 Markdown 预处理
-md2docx format --file docs/example.md
+md2docx format -f report.md
 
-# 导出可编辑的默认配置和样式
+# 导出内置默认配置和样式
 md2docx export config
 md2docx export style
 
-# 从现有 Word 文档提取样式
-md2docx export style --file template.docx
+# 从现有 DOCX 提取样式
+md2docx export style -f template.docx
+
+# 删除 ~/.md2docx 中的中间文件和缓存
+md2docx clean
 ```
 
-所有写文件命令默认拒绝覆盖已有文件。确认覆盖时传入 `--force`。
-不传入任何参数时显示顶层帮助，行为与 `md2docx --help` 相同。
+所有写文件命令默认拒绝覆盖已有文件。确认覆盖时显式传入 `--force`。
 
-## CLI
+## CLI 参考
 
-```text
-md2docx -f <markdown> [选项]
+```shell
+md2docx <markdown>
+md2docx -f <markdown> [转换选项]
 md2docx format -f <markdown> [选项]
 md2docx export config [选项]
 md2docx export style [选项]
+md2docx clean
 ```
 
-`--file` 在顶层转换和 `format` 命令中必填；在 `export style` 中可选，不提供时导出内置默认样式，提供 DOCX 时从该文档提取样式。
+### 转换
 
-| 参数                  | 说明                           |
-| --------------------- | ------------------------------ |
-| `-f, --file <path>`   | 输入文件                       |
-| `-c, --config <path>` | 自定义配置文件                 |
-| `-s, --style <path>`  | 自定义样式文件（仅 Word 转换） |
-| `-o, --output <path>` | 完整输出文件路径               |
-| `--force`             | 覆盖已有输出                   |
-| `-h, --help`          | 显示当前命令帮助               |
-| `-v, --version`       | 显示版本号                     |
+| 参数                  | 说明                                     |
+| --------------------- | ---------------------------------------- |
+| `<markdown>`          | 位置参数；仅在没有其他转换选项时允许使用 |
+| `-f, --file <path>`   | Markdown 输入文件                        |
+| `-c, --config <path>` | 自定义配置 JSON                          |
+| `-s, --style <path>`  | 自定义样式 JSON                          |
+| `-o, --output <path>` | DOCX 输出路径                            |
+| `--force`             | 覆盖已有输出                             |
+| `-h, --help`          | 显示帮助                                 |
+| `-v, --version`       | 显示版本号                               |
 
-默认输出分别为 `<源文件名>.docx`、`<源文件名>_formatted.md`、`config.json` 和
-`style.json`。从 DOCX 提取样式时，默认输出 `<DOCX 文件名>_style.json`。
+位置参数不能和 `--file`、`--config`、`--style`、`--output` 或 `--force` 混用。例如：
 
-## 配置
+```bash
+md2docx report.md                 # 正确
+md2docx report.md --force         # 错误
+md2docx -f report.md --force      # 正确
+```
 
-配置文件位于 `config/config.json`，通过 JSON Schema 提供 IDE 校验。使用
-`md2docx export config` 导出副本，修改后通过 `--config` 指定；CLI 不提供单个配置项覆盖。
-
-| 配置项                           | 说明                                                         | 默认值                |
-| -------------------------------- | ------------------------------------------------------------ | --------------------- |
-| `detectTitle.enabled`            | 自动设置文档标题                                             | `true`                |
-| `detectTitle.strategy`           | 标题来源策略：`first-h1` / `single-h1` / `filename` / `none` | `"first-h1"`          |
-| `normalizeHeadings.enabled`      | 自动修正标题层级                                             | `true`                |
-| `numberHeadings.enabled`         | 自动为标题编号（开启时自动启用 normalizeHeadings）           | `true`                |
-| `numberHeadings.detectExisting`  | 重新编号前移除已有编号                                       | `true`                |
-| `numberHeadings.useBuiltinRules` | 识别常见的中文和数字编号                                     | `true`                |
-| `figureCaption.enabled`          | 自动为图片编号（格式：`图 {n}`）                             | `true`                |
-| `figureCaption.format`           | 图片编号格式                                                 | `"图 {n}"`            |
-| `figureCaption.separator`        | 编号与标题之间的分隔符                                       | `"："`                |
-| `tableCaption.enabled`           | 自动为表格编号（格式：`表 {n}`）                             | `true`                |
-| `tableCaption.format`            | 表格编号格式                                                 | `"表 {n}"`            |
-| `tableCaption.separator`         | 编号与标题之间的分隔符                                       | `" "`                 |
-| `renderMermaid.enabled`          | 渲染 Mermaid 图表为 PNG                                      | `true`                |
-| `renderMermaid.theme`            | 图表主题                                                     | `"tokyo-night-light"` |
-| `renderMermaid.density`          | 图片清晰度（DPI，最小 72）                                   | `200`                 |
+### format
 
-## 样式定制
+`format` 运行完整 Markdown 预处理，但不生成 DOCX，也不调用 Pandoc。
 
-`config/style.json` 定义了 docx 输出的全部样式，包括字体、字号、颜色、缩进、间距等。
+| 参数                  | 说明                                        |
+| --------------------- | ------------------------------------------- |
+| `-f, --file <path>`   | 必填，Markdown 输入文件                     |
+| `-c, --config <path>` | 自定义配置 JSON                             |
+| `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
+| `--force`             | 覆盖已有输出                                |
 
-### 从模板 docx 提取样式
+### export
 
-如果你有一个排版精美的 docx 模板，可以提取其样式：
+```bash
+md2docx export config [-o config.json] [--force]
+md2docx export style [-f template.docx] [-o style.json] [--force]
+```
+
+`export config` 导出内置默认配置。`export style` 不带 `--file` 时导出内置默认样式；指定 DOCX 时从该文档提取样式。
+
+### clean
 
 ```bash
-md2docx export style --file template.docx
+md2docx clean
 ```
 
-提取后修改 `config/style.json`，转换时会自动使用这些样式生成输出文档。
+`clean` 只允许删除当前用户主目录下严格匹配的 `~/.md2docx/`。如果目标是符号链接，只删除链接本身。命令可重复执行；目录不存在时正常退出。
+
+npm 卸载不会可靠地清理用户数据。卸载前如需清理，请显式运行：
 
-### 手动维护样式
+```bash
+md2docx clean
+npm uninstall -g @v1hz/md2docx
+```
 
-可直接编辑 `config/style.json`。支持以下样式配置：
+## 默认输出
 
-- **文档默认样式**（`default.document`）：全局字体、字号、段落间距
-- **内置样式覆盖**（`default.heading1` … `default.heading6`、`default.title` 等）
-- **自定义段落样式**（`paragraphStyles`）
-- **自定义字符样式**（`characterStyles`）
+```text
+md2docx report.md                     → ./report.docx
+md2docx -f report.md                  → ./report.docx
+md2docx format -f report.md           → ./report_formatted.md
+md2docx export config                 → ./config.json
+md2docx export style                  → ./style.json
+md2docx export style -f template.docx → ./template_style.json
+```
 
-详细的样式字段定义参考 [docx 包文档](https://docx.js.org)。
+## 中间文件与缓存
 
-## 处理流水线
+所有运行时资源统一位于：
 
-项目遵循单向处理流水线，每个步骤职责单一。
+```text
+~/.md2docx/
+├── preprocess/
+│   └── <输入文件名>-<绝对路径哈希>/
+│       ├── <输入文件名>_formatted.md
+│       └── mermaid_*.png
+├── resources/
+│   ├── config.json
+│   ├── style.json
+│   └── add-inline-code.lua
+└── style/
+    └── <样式内容哈希>.docx
+```
+
+输入文件的绝对路径参与目录哈希，因此不同目录下的同名 Markdown 不会复用中间文件。内置资源会在需要时写入 `resources/`；样式模板按样式内容哈希缓存。
+
+输出 DOCX 和显式导出的配置、样式仍写到用户指定位置或当前工作目录，不会写入缓存目录。
+
+## 配置
 
+内置配置来自 `config/config.json`，并由 `config/config.schema.json` 提供 JSON Schema。推荐先导出再编辑：
+
+```bash
+md2docx export config
+md2docx -f report.md -c config.json
 ```
+
+CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
+
+| 配置项                           | 说明                                           | 默认值                |
+| -------------------------------- | ---------------------------------------------- | --------------------- |
+| `detectTitle.enabled`            | 自动设置文档标题                               | `true`                |
+| `detectTitle.strategy`           | `first-h1` / `single-h1` / `filename` / `none` | `"first-h1"`          |
+| `normalizeHeadings.enabled`      | 修正标题起始层级与层级跳跃                     | `true`                |
+| `numberHeadings.enabled`         | 为标题添加多级编号                             | `true`                |
+| `numberHeadings.detectExisting`  | 重新编号前移除已识别的编号                     | `true`                |
+| `numberHeadings.useBuiltinRules` | 使用内置中文和数字编号识别规则                 | `true`                |
+| `figureCaption.enabled`          | 为独立图片添加题注                             | `true`                |
+| `figureCaption.format`           | 图片编号格式                                   | `"图 {n}"`            |
+| `figureCaption.separator`        | 图片编号与标题之间的分隔符                     | `"："`                |
+| `tableCaption.enabled`           | 为表格添加题注                                 | `true`                |
+| `tableCaption.format`            | 表格编号格式                                   | `"表 {n}"`            |
+| `tableCaption.separator`         | 表格编号与标题之间的分隔符                     | `" "`                 |
+| `renderMermaid.enabled`          | 将 Mermaid 渲染为 PNG                          | `true`                |
+| `renderMermaid.theme`            | beautiful-mermaid 主题                         | `"tokyo-night-light"` |
+| `renderMermaid.density`          | PNG 输出 DPI，最小值 72                        | `200`                 |
+
+## 样式定制
+
+`config/style.json` 定义 DOCX 的默认样式、标题样式、段落样式和字符样式。转换时，项目用 `docx` 生成 reference DOCX，再通过 Pandoc 的 `--reference-doc` 应用样式。
+
+### 从现有 DOCX 提取
+
+```bash
+md2docx export style -f template.docx
+md2docx -f report.md -s template_style.json
+```
+
+### 手动维护
+
+主要区域包括：
+
+- `default.document`：全局字体、字号与段落设置
+- `default.heading1` 至 `default.heading6`：标题样式
+- `default.title`：文档标题样式
+- `paragraphStyles`：自定义段落样式
+- `characterStyles`：自定义字符样式
+- `tableStylesXml`：从 DOCX 提取并重新注入的表格样式 XML
+
+基于 `a0`（Body Text）的样式会继承首行缩进。如果子样式不需要缩进，应在 `indent` 中显式清零。
+
+## Mermaid 渲染
+
+渲染流程如下：
+
+```text
+Mermaid
+→ beautiful-mermaid
+→ SVG
+→ 内联 CSS var() / color-mix()
+→ @resvg/resvg-wasm
+→ 写入正确的 PNG DPI 元数据
+→ PNG
+```
+
+resvg 不直接支持 beautiful-mermaid 输出中的所有 CSS 自定义属性，因此转换前会解析：
+
+- `var(--name)`
+- `var(--name, fallback)`
+- 嵌套 fallback
+- `color-mix(in srgb, ...)`
+- 三位和六位十六进制颜色
+
+Windows 会显式加载微软雅黑、Arial 和 Consolas；macOS 与 Linux 使用各自的候选系统字体。PNG 像素尺寸和 `pHYs` DPI 元数据都与 `renderMermaid.density` 保持一致。
+
+运行时不依赖 Sharp。Sharp 只作为开发依赖，用于测试中比较 resvg 与旧渲染结果，不会打入 npm 运行时包或平台 EXE。
+
+## 处理流水线
+
+```text
 Markdown
     ↓
 解析 AST
     ↓
-addTitle()            ← 提取文档标题
+addTitle()
     ↓
-normalizeHeadings()   ← 修正标题层级（最小深度 → H1，消除跳跃）
+normalizeHeadings()
     ↓
-numberHeadings()      ← 添加标题编号（1 / 1.1 / 1.1.1 …）
+numberHeadings()
     ↓
-numberTables()         ← 添加表格编号（表 1、表 2 …）
+numberTables()
     ↓
-renderMermaid()       ← Mermaid 代码块 → PNG 图片
+renderMermaid()
     ↓
-numberPictures()      ← 添加图片编号（图 1、图 2 …）
+numberPictures()
     ↓
 序列化 Markdown
     ↓
-生成样式模板 docx     ← 根据 config/style.json 生成 pandoc reference-doc
+生成或复用 reference DOCX
+    ↓
+Pandoc + Lua filter
     ↓
-pandoc → DOCX         ← 以 --reference-doc 传入样式模板
+DOCX
 ```
 
-## 开发
+`numberTables()` 必须先于 Mermaid 渲染；`numberPictures()` 必须后于 Mermaid 渲染，这样 Mermaid 生成的图片也能获得图题。
 
-### 从源码运行
+## 构建
 
-从源码开发需要安装 Bun；发布后的 CLI 使用 Node.js 运行，不依赖 Bun。
+从源码开发需要 [Bun](https://bun.sh/)。
 
 ```bash
 git clone https://github.com/WXY-V1hZ/md2docx.git
 cd md2docx
 bun install
-bun run src/index.ts --file docs/example.md
+
+# 从源码运行
+bun run src/index.ts report.md
+
+# 测试和静态检查
+bun test
+bun check
 ```
 
-### 命令
+### npm 构建
 
 ```bash
-# 测试
-bun test
+bun run build
+```
 
-# 类型检查 + 代码检查 + 格式检查
-bun check
+输出：
 
-# 查看 CLI 帮助
-bun run src/index.ts --help
+```text
+dist/
+├── index.js
+└── index_bg.wasm
+```
+
+依赖会打包进 `index.js`，resvg WASM 作为相邻资源输出。`prepack` 会自动执行此构建。
+
+### 平台可执行文件
+
+```bash
+bun run build:exe
+```
+
+Windows 输出为 `dist/md2docx.exe`。该程序只适用于构建目标对应的操作系统和 CPU 架构。
+
+`build` 和 `build:exe` 都会先删除整个 `dist/`，因此两种产物不会同时保留。尤其不要依赖手工生成的 EXE 参与 `npm publish`：发布时 `prepack` 会重新生成 npm 所需的 `index.js` 和 WASM。
+
+## 常见问题
+
+### 找不到 Pandoc
+
+先检查：
+
+```bash
+pandoc --version
+```
+
+如果命令不存在，请从 [Pandoc 官方安装页](https://pandoc.org/installing.html) 安装，并重新打开终端使 `PATH` 生效。
+
+### 输出文件已存在
+
+默认不会覆盖文件。确认目标可以覆盖后使用：
+
+```bash
+md2docx -f report.md --force
 ```
 
 ## 许可
 
-本项目基于 GNU General Public License v3.0 开源 — 详见 [LICENSE](LICENSE)。
+md2docx 以 [GNU GPL v3.0](LICENSE) 发布。