@v1hz/md2docx 2.6.0 → 2.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +125 -376
  2. package/dist/index.js +273 -106
  3. package/dist-electron/main.js +152518 -0
  4. package/package.json +24 -3
package/README.md CHANGED
@@ -17,466 +17,215 @@
17
17
 
18
18
  ## 功能
19
19
 
20
- | 功能 | 说明 |
21
- | ----------------- | ---------------------------------------------------------------- |
22
- | 文档标题 | 从 YAML frontmatter、H1 或文件名提取标题 |
23
- | 标题层级归一化 | 将最浅标题归一化为 H1，并修复标题层级跳跃 |
24
- | 标题编号 | 生成 `1`、`1.1`、`1.1.1` 等编号，并可剥离常见的已有中英文编号 |
25
- | 表格与图片编号 | 自动生成“表 1”“图 1：标题”等题注 |
26
- | 图片尺寸限制 | 按自然尺寸等比缩小超过最大宽度或高度的图片 |
27
- | Mermaid 图表 | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG |
28
- | Word 样式 | 支持受控语义化配置和完整底层样式，也可从现有 DOCX 提取样式 |
29
- | 配置预设 | 将处理配置和两层 Word 样式保存为可切换、可继承默认值的预设 |
30
- | Markdown 格式化 | 可只运行预处理流水线，输出格式化后的 Markdown |
31
- | 去除分隔符 | 默认移除 `---`、`***`、`___` 等分隔符行，减少无用页面间距 |
32
- | 集中缓存 | 中间文件统一存储到 `~/.md2docx/`，不会在当前目录创建 `tmp/` |
33
- | Node 与可执行版本 | 支持 npm CLI，也支持构建不依赖 Node.js/Bun 的 Windows 可执行文件 |
20
+ - **文档标题** — 从 YAML frontmatter、H1 或文件名提取
21
+ - **标题归一化** — 最浅标题 → H1，修复层级跳跃
22
+ - **标题编号** — `1`、`1.1`、`1.1.1`，可剥离已有中英文编号
23
+ - **表格与图片题注** — "表 1"、"图 1：标题"
24
+ - **图片尺寸限制** — 等比缩小超限图片
25
+ - **Mermaid 渲染** — beautiful-mermaid + resvg-wasm → 高 DPI PNG
26
+ - **Word 样式** — 语义化配置 / 完整底层样式 / 从 DOCX 提取
27
+ - **预设系统** — 可切换、可继承默认值的配置与样式预设
28
+ - **Markdown 格式化** — 只运行预处理流水线
29
+ - **桌面图形界面** — Electron + Vue 3，支持文件拖放、批量转换、预设编辑、转换历史、自动更新
30
+ - **集中缓存** — `~/.md2docx/`，工作目录保持干净
31
+ - **双构建** — npm CLI + Windows 单文件 EXE + 桌面安装包
34
32
 
35
- ## AI 辅助
36
-
37
- 本仓库提供 [`SKILL.md`](SKILL.md)，是供 AI 代码助手（如 Zed、Cursor、GitHub Copilot）使用的技能描述文件。在 AI 对话中引用此文件，AI 就能正确使用 `md2docx` CLI 完成转换、格式化、样式定制和导出等操作。
38
-
39
- ## 安装方式
40
-
41
- ### npm CLI
33
+ ---
42
34
 
43
- 前置依赖：
35
+ ## 安装
44
36
 
45
- - [Node.js 22.12+](https://nodejs.org/)
46
- - [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用；图片尺寸限制需要 Pandoc 3.1.13+
37
+ 前置：Node.js 22.12+, [Pandoc](https://pandoc.org/installing.html)（需在 PATH 中；图片尺寸限制需 Pandoc 3.1.13+）
47
38
 
48
39
  ```bash
49
40
  npm install -g @v1hz/md2docx
50
- md2docx --version
51
- md2docx report.md
41
+ # 或
42
+ npx @v1hz/md2docx report.md
52
43
  ```
53
44
 
54
- 也可以不全局安装：
45
+ Windows 桌面用户也可下载安装版或便携版（见 [Releases](https://github.com/WXY-V1hZ/md2docx/releases)）。
55
46
 
56
- ```bash
57
- npx @v1hz/md2docx report.md
58
- ```
47
+ ---
59
48
 
60
49
  ## 快速开始
61
50
 
62
51
  ```bash
63
- # 只有输入路径时，可以省略 --file
64
- md2docx report.md
65
-
66
- # 使用任何转换选项时，输入必须通过 --file 指定
67
- md2docx --file report.md --output output/report.docx
68
-
69
- # 使用自定义配置、底层样式和语义化样式配置
70
- md2docx -f report.md -c config.json --style-raw style-raw.json --style-config style-config.json
71
-
72
- # 保存并使用预设
73
- md2docx preset save --name academic --config config.json --style-config style-config.json
52
+ md2docx report.md # 仅路径，默认输出 ./report.docx
53
+ md2docx -f report.md -o output.docx # 带选项（必须有 --file）
54
+ md2docx -f report.md -c config.json --style-raw raw.json --style-config style-config.json
55
+ md2docx preset save --name academic --config config.json
74
56
  md2docx preset use academic
75
-
76
- # 只执行 Markdown 预处理
77
- md2docx format -f report.md
78
-
79
- # 导出内置默认配置、底层样式和语义化样式配置
80
- md2docx export config
81
- md2docx export style-raw
82
- md2docx export style-config
83
-
84
- # 从现有 DOCX 提取样式
85
- md2docx export style-raw -f template.docx
86
-
87
- # 删除 ~/.md2docx 中的中间文件和缓存
88
- md2docx clean
57
+ md2docx format -f report.md # 只格式化
58
+ md2docx export config # 导出默认配置
59
+ md2docx export style-raw -f template.docx # 从 DOCX 提取样式
60
+ md2docx clean # 清除预处理/资源/样式缓存
89
61
  ```
90
62
 
91
63
  所有写文件命令默认覆盖已有输出。
92
64
 
65
+ ---
66
+
93
67
  ## CLI 参考
94
68
 
95
- ```shell
69
+ ```text
96
70
  md2docx <markdown>
97
71
  md2docx -f <markdown> [转换选项]
98
72
  md2docx format -f <markdown> [选项]
99
- md2docx export config [选项]
100
- md2docx export style-raw [选项]
101
- md2docx export style-config [选项]
102
- md2docx preset list
103
- md2docx preset use <name>
104
- md2docx preset save --name <name> [配置选项]
73
+ md2docx export config|style-raw|style-config [选项]
74
+ md2docx preset list|use <name>|save --name <name> [选项]
105
75
  md2docx clean
106
76
  ```
107
77
 
108
- ### 转换
109
-
110
- | 参数 | 说明 |
111
- | ----------------------- | ---------------------------------------- |
112
- | `<markdown>` | 位置参数；仅在没有其他转换选项时允许使用 |
113
- | `-f, --file <path>` | Markdown 输入文件 |
114
- | `--preset <name>` | 本次转换使用指定预设 |
115
- | `-c, --config <path>` | 自定义配置 JSON |
116
- | `--style-raw <path>` | 完整底层 Word 样式 JSON |
117
- | `--style-config <path>` | 受控语义化样式配置 JSON |
118
- | `-o, --output <path>` | DOCX 输出路径 |
119
- | `-h, --help` | 显示帮助 |
120
- | `-v, --version` | 显示版本号 |
121
-
122
- 位置参数不能和 `--file`、`--preset`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
123
-
124
- ```bash
125
- md2docx report.md # 正确
126
- md2docx report.md -o report.docx # 错误
127
- md2docx -f report.md -o report.docx # 正确
128
- ```
129
-
130
- ### format
131
-
132
- `format` 运行完整 Markdown 预处理，但不生成 DOCX，也不调用 Pandoc。
133
-
134
- | 参数 | 说明 |
135
- | --------------------- | ------------------------------------------- |
136
- | `-f, --file <path>` | 必填，Markdown 输入文件 |
137
- | `--preset <name>` | 使用预设中的 `config.json` |
138
- | `-c, --config <path>` | 自定义配置 JSON |
139
- | `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
140
-
141
- ### export
142
-
143
- ```bash
144
- md2docx export config [-o config.json]
145
- md2docx export style-raw [-f template.docx] [-o style-raw.json]
146
- md2docx export style-config [-o style-config.json]
147
- ```
78
+ | 参数 | 说明 |
79
+ | ----------------------- | ---------------------------- |
80
+ | `<markdown>` | 位置参数，仅无其他选项时可用 |
81
+ | `-f, --file <path>` | Markdown 输入 |
82
+ | `--preset <name>` | 本次指定预设 |
83
+ | `-c, --config <path>` | 配置 JSON |
84
+ | `--style-raw <path>` | 底层 Word 样式 JSON |
85
+ | `--style-config <path>` | 语义化样式配置 JSON |
86
+ | `-o, --output <path>` | DOCX 输出（format 为 `.md`） |
148
87
 
149
- `export config` 导出内置 Markdown 处理配置。`export style-raw` 不带 `--file` 时导出内置底层 Word 样式；指定 DOCX 时从该文档提取底层样式。`export style-config` 导出默认语义化样式配置。
88
+ 位置参数不能与 `--file` 或其他选项混用。`format` 必须提供 `--file`，不接受样式参数，不调用 Pandoc。
150
89
 
151
- ### preset
90
+ ### 默认输出路径
152
91
 
153
- ```bash
154
- md2docx preset list
155
- md2docx preset use academic
156
- md2docx preset use default
157
- md2docx preset save --name academic \
158
- --config config.json \
159
- --style-raw style-raw.json \
160
- --style-config style-config.json
92
+ ```text
93
+ report.md → ./report.docx
94
+ format -f report.md → ./report_formatted.md
95
+ export config → ./config.json
96
+ export style-raw → ./style-raw.json
97
+ export style-raw -f t.docx → ./t_style-raw.json
98
+ export style-config → ./style-config.json
161
99
  ```
162
100
 
163
- 用户预设位于 `~/.md2docx/presets/<name>/`，其中三个标准 JSON 文件都可省略；缺失项逐一继承系统内置 `default`。文件存在但内容无效时会报错。`preset save` 至少需要一个配置文件，同名保存会完整替换旧预设，未提供的类型改为继承默认值。`--preset` 只影响本次执行，`preset use` 会持久化默认选择。
164
-
165
- ### clean
101
+ ---
166
102
 
167
- ```bash
168
- md2docx clean
169
- ```
103
+ ## 桌面应用
170
104
 
171
- `clean` 只删除 `~/.md2docx/` 下可重建的预处理文件、物化资源和样式缓存，保留 `presets/` 与 `settings.json`。命令拒绝跟随符号链接，且可重复执行。
105
+ 仓库包含 Electron 桌面端（Windows 安装版支持自动更新）。主要功能：
172
106
 
173
- npm 卸载不会可靠地清理用户数据。卸载前如需清理，请显式运行：
107
+ - **文件管理**：拖入 `.md` 文件或粘贴 Markdown 文本进行转换，支持批量
108
+ - **转换侧边栏**（`Ctrl+Alt+B`）：实时调整输出目录、命名策略、样式等配置
109
+ - **预设可视化编辑**：创建、编辑、管理预设，内置 `default` 只读，自定义时自动保存为新预设
110
+ - **转换记录**：最多 30 条，可打开输出、定位文件或重新转换
111
+ - **设置面板**：Pandoc 检测、输出设置、更新检查
174
112
 
175
113
  ```bash
176
- md2docx clean
177
- npm uninstall -g @v1hz/md2docx
178
- ```
179
-
180
- ## 默认输出
181
-
182
- ```text
183
- md2docx report.md → ./report.docx
184
- md2docx -f report.md → ./report.docx
185
- md2docx format -f report.md → ./report_formatted.md
186
- md2docx export config → ./config.json
187
- md2docx export style-raw → ./style-raw.json
188
- md2docx export style-raw -f template.docx → ./template_style-raw.json
189
- md2docx export style-config → ./style-config.json
190
- ```
191
-
192
- ## 中间文件与缓存
193
-
194
- 所有运行时资源统一位于：
195
-
196
- ```text
197
- ~/.md2docx/
198
- ├── settings.json
199
- ├── presets/
200
- │ └── <预设名称>/
201
- │ ├── config.json（可选）
202
- │ ├── style-raw.json（可选）
203
- │ └── style-config.json（可选）
204
- ├── preprocess/
205
- │ └── <输入文件名>-<绝对路径哈希>/
206
- │ ├── <输入文件名>_formatted.md
207
- │ └── mermaid_*.png
208
- ├── resources/
209
- │ ├── default/
210
- │ │ ├── config.json
211
- │ │ ├── style-config.json
212
- │ │ └── style-raw.json
213
- │ ├── add-inline-code.lua
214
- │ └── limit-image-size.lua
215
- └── style/
216
- └── <样式内容哈希>.docx
114
+ bun run build:electron # 构建主进程与 preload
115
+ bun run electron # 构建并启动桌面端
116
+ bun run dev # 开发模式（隔离 Chromium 缓存）
117
+ bun run pack # 构建 Windows NSIS 安装版（含自动更新）
118
+ bun run pack:portable # 构建便携版
217
119
  ```
218
120
 
219
- 输入文件的绝对路径参与目录哈希，因此不同目录下的同名 Markdown 不会复用中间文件。内置资源会在需要时写入 `resources/`；样式模板按样式内容哈希缓存。
220
-
221
- 输出 DOCX 和显式导出的配置、样式仍写到用户指定位置或当前工作目录，不会写入缓存目录。
222
-
223
- 虽然 Pandoc 实际读取的是缓存中的格式化 Markdown，但本地相对资源始终优先相对于**原始 Markdown 所在目录**解析；找不到时再搜索命令运行目录。例如 `C:/docs/example.md` 中的 `./pictures/test.png` 会解析为 `C:/docs/pictures/test.png`，与从哪个目录执行 `md2docx` 无关。绝对路径、HTTP(S) URL 和 Mermaid 生成的缓存图片不受影响。
121
+ ---
224
122
 
225
123
  ## 配置
226
124
 
227
- 内置配置来自 `config/default/config.json`，并由 `config/config.schema.json` 提供 JSON Schema。推荐先导出再编辑：
125
+ 内置配置来自 `config/default/config.json`（`config/config.schema.json` 提供校验），推荐先导出再编辑：
228
126
 
229
127
  ```bash
230
128
  md2docx export config
231
129
  md2docx -f report.md -c config.json
232
130
  ```
233
131
 
234
- CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
235
-
236
- | 配置项 | 说明 | 默认值 |
237
- | -------------------------------- | ---------------------------------------------- | --------------------- |
238
- | `detectTitle.enabled` | 自动设置文档标题 | `true` |
239
- | `detectTitle.strategy` | `first-h1` / `single-h1` / `filename` / `none` | `"first-h1"` |
240
- | `normalizeHeadings.enabled` | 修正标题起始层级与层级跳跃 | `true` |
241
- | `numberHeadings.enabled` | 为标题添加多级编号 | `true` |
242
- | `numberHeadings.detectExisting` | 重新编号前移除已识别的编号 | `true` |
243
- | `numberHeadings.useBuiltinRules` | 使用内置中文和数字编号识别规则 | `true` |
244
- | `figureCaption.enabled` | 为独立图片添加题注 | `true` |
245
- | `figureCaption.format` | 图片编号格式 | `"图 {n}"` |
246
- | `figureCaption.separator` | 图片编号与标题之间的分隔符 | `"："` |
247
- | `tableCaption.enabled` | 为表格添加题注 | `true` |
248
- | `tableCaption.format` | 表格编号格式 | `"表 {n}"` |
249
- | `tableCaption.separator` | 表格编号与标题之间的分隔符 | `" "` |
250
- | `renderMermaid.enabled` | 将 Mermaid 渲染为 PNG | `true` |
251
- | `renderMermaid.theme` | beautiful-mermaid 主题 | `"tokyo-night-light"` |
252
- | `renderMermaid.density` | PNG 输出 DPI，最小值 72 | `200` |
253
- | `imageSize.enabled` | 等比缩小超过尺寸限制的图片 | `true` |
254
- | `imageSize.maxWidthCm` | DOCX 图片最大宽度（厘米） | `12` |
255
- | `imageSize.maxHeightCm` | DOCX 图片最大高度（厘米） | `12` |
256
- | `removeThematicBreaks.enabled` | 移除 `---`、`***`、`___` 等分隔符行 | `true` |
257
-
258
- 图片尺寸限制在 Pandoc 生成 DOCX 前通过 Lua filter 应用。程序读取图片像素尺寸和 DPI，仅缩小超限图片，不会放大小图；宽度和高度使用同一缩放比例。Markdown 中已经显式设置 `width` 或 `height` 的图片视为用户覆盖，不应用全局限制。单张图片无法读取尺寸时会输出警告并继续转换。
259
-
260
- ## 样式定制
132
+ | 配置项 | 说明 | 默认值 |
133
+ | --------------------------------------------------------- | ----------------------------------------------- | -------------------------------------- |
134
+ | `detectTitle.enabled / strategy` | 自动设置标题 / first-h1/single-h1/filename/none | `true` / `"first-h1"` |
135
+ | `numberHeadings.{enabled,detectExisting,useBuiltinRules}` | 标题编号 / 剥离已有编号 | `true` / `true` / `true` |
136
+ | `figureCaption.{enabled,format,separator}` | 图片题注 / `"图 {n}"` / `"："` | `true` |
137
+ | `tableCaption.{enabled,format,separator}` | 表格题注 / `"表 {n}"` / `" "` | `true` |
138
+ | `renderMermaid.{enabled,theme,density}` | Mermaid 渲染 / 主题 / DPI（≥72） | `true` / `"tokyo-night-light"` / `200` |
139
+ | `imageSize.{enabled,maxWidthCm,maxHeightCm}` | 图片尺寸限制（厘米） | `true` / `12` / `12` |
140
+ | `removeThematicBreaks.enabled` | 移除分隔符行 | `true` |
141
+ | `normalizeHeadings.enabled` | 修正标题层级 | `true` |
261
142
 
262
- 普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
263
-
264
- 仓库中的 `config/default/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。完整底层 Word 样式位于 `config/default/style-raw.json`。
265
-
266
- ```json
267
- {
268
- "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
269
- "schemaVersion": 1,
270
- "options": {
271
- "body": {
272
- "firstLineIndent": false,
273
- "lineSpacing": "onePointFive"
274
- },
275
- "headings": {
276
- "1": {
277
- "startOnNewPage": false,
278
- "alignment": "left",
279
- "bold": true
280
- },
281
- "2": {
282
- "bold": true
283
- },
284
- "3": {
285
- "bold": true
286
- },
287
- "4": {
288
- "bold": true,
289
- "italic": false
290
- },
291
- "5": {
292
- "bold": true,
293
- "italic": false
294
- },
295
- "6": {
296
- "bold": true,
297
- "italic": false
298
- }
299
- },
300
- "inlineCode": {
301
- "background": false
302
- },
303
- "codeBlock": {
304
- "border": false
305
- }
306
- }
307
- }
308
- ```
143
+ 图片尺寸限制：超限等比缩小，不放大小图；已显式设 width/height 时不应用；读取失败时警告并继续。
309
144
 
310
- 将配置保存为 `style-config.json` 后使用：
311
-
312
- ```bash
313
- md2docx -f report.md --style-config style-config.json
314
- ```
145
+ ---
315
146
 
316
- 字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。正文行距为浮点数倍数，例如 `1.5` 表示 1.5 倍行距；一级标题对齐只接受 `left`、`center`。当前还开放一至六级标题粗体，以及四至六级标题斜体。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
147
+ ## 样式定制
317
148
 
318
- 转换时按以下规则选择输入：
149
+ 语义化配置（`config/default/style-config.json`）开放常用 Word 样式白名单：
319
150
 
320
- | 参数 | 行为 |
321
- | ------------------- | ----------------------------------- |
322
- | 都不指定 | 当前预设 raw + 当前预设 config |
323
- | 仅 `--style-raw` | 直接使用用户 raw，不应用默认 config |
324
- | 仅 `--style-config` | 用户 config 应用到当前预设 raw |
325
- | 两者都指定 | 用户 config 应用到用户 raw |
151
+ - `body.firstLineIndent` — 正文首行缩进
152
+ - `body.lineSpacing` — 行距倍数（如 `1.5`）
153
+ - `headings["1"]` — `startOnNewPage`、`alignment`（left/center）、`bold`
154
+ - `headings["2".."6"]` — `bold`
155
+ - `headings["4".."6"]` — `italic`
156
+ - `inlineCode.background` — 行内代码背景
157
+ - `codeBlock.border` — 代码块外框
326
158
 
327
- 最终有效的底层样式用于生成 reference DOCX，并通过 Pandoc 的 `--reference-doc` 应用。`--style-raw` 和 `--style-config` 类型固定，不能互换。
159
+ 输入组合：
328
160
 
329
- ### 从现有 DOCX 提取
161
+ | 参数 | 行为 |
162
+ | ------------------- | ----------------------------- |
163
+ | 都不指定 | 当前预设 raw + config |
164
+ | 仅 `--style-raw` | 直接使用 raw，不读默认 config |
165
+ | 仅 `--style-config` | config 应用到当前预设 raw |
166
+ | 两者都指定 | config 应用到用户 raw |
330
167
 
331
168
  ```bash
169
+ md2docx export style-config
170
+ md2docx -f report.md --style-config style-config.json
332
171
  md2docx export style-raw -f template.docx
333
172
  md2docx -f report.md --style-raw template_style-raw.json
334
173
  ```
335
174
 
336
- ### 高级手动维护
337
-
338
- 主要区域包括：
339
-
340
- - `default.document`：全局字体、字号与段落设置
341
- - `default.heading1` 至 `default.heading6`：标题样式
342
- - `default.title`：文档标题样式
343
- - `paragraphStyles`：自定义段落样式
344
- - `characterStyles`：自定义字符样式
345
- - `tableStylesXml`：从 DOCX 提取并重新注入的表格样式 XML
346
-
347
- 基于 `a0`（Body Text）的样式会继承首行缩进。如果子样式不需要缩进，应在 `indent` 中显式清零。
348
-
349
- ## Mermaid 渲染
350
-
351
- 渲染流程如下：
352
-
353
- ```text
354
- Mermaid
355
- → beautiful-mermaid
356
- → SVG
357
- → 内联 CSS var() / color-mix()
358
- → @resvg/resvg-wasm
359
- → 写入正确的 PNG DPI 元数据
360
- → PNG
361
- ```
362
-
363
- resvg 不直接支持 beautiful-mermaid 输出中的所有 CSS 自定义属性，因此转换前会解析：
175
+ 字段缺失继承底层样式；`true` 写入完整效果；`false` 写入 Word 关闭值。详见 [`docs/style-config-design.md`](docs/style-config-design.md)。
364
176
 
365
- - `var(--name)`
366
- - `var(--name, fallback)`
367
- - 嵌套 fallback
368
- - `color-mix(in srgb, ...)`
369
- - 三位和六位十六进制颜色
370
-
371
- Windows 会显式加载微软雅黑、Arial 和 Consolas；macOS 与 Linux 使用各自的候选系统字体。PNG 像素尺寸和 `pHYs` DPI 元数据都与 `renderMermaid.density` 保持一致。
372
-
373
- 运行时不依赖 Sharp。Sharp 只作为开发依赖，用于测试中比较 resvg 与旧渲染结果，不会打入 npm 运行时包或平台 EXE。
177
+ ---
374
178
 
375
179
  ## 处理流水线
376
180
 
377
- ```text
378
- Markdown
379
- ↓
380
- 解析 AST
381
- ↓
382
- addTitle()
383
- ↓
384
- removeThematicBreaks()
385
- ↓
386
- normalizeHeadings()
387
- ↓
388
- numberHeadings()
389
- ↓
390
- numberTables()
391
- ↓
392
- renderMermaid()
393
- ↓
394
- numberPictures()
395
- ↓
396
- 序列化 Markdown
397
- ↓
398
- 生成或复用 reference DOCX
399
- ↓
400
- Pandoc + 行内代码/图片尺寸 Lua filter
401
- ↓
402
- DOCX
403
181
  ```
404
-
405
- `removeThematicBreaks()` 在标题处理之前执行，避免分隔符干扰文档结构。
406
- `numberTables()` 必须先于 Mermaid 渲染；`numberPictures()` 必须后于 Mermaid 渲染，这样 Mermaid 生成的图片也能获得图题。
407
-
408
- ## 构建
409
-
410
- 从源码开发需要 [Bun](https://bun.sh/)。
411
-
412
- ```bash
413
- git clone https://github.com/WXY-V1hZ/md2docx.git
414
- cd md2docx
415
- bun install
416
-
417
- # 从源码运行
418
- bun run src/index.ts report.md
419
-
420
- # 测试和静态检查
421
- bun test
422
- bun check
182
+ Markdown → AST → addTitle → removeThematicBreaks → normalizeHeadings
183
+ → numberHeadings → numberTables → renderMermaid → numberPictures
184
+ → 序列化 → reference DOCX → Pandoc + Lua filter → DOCX
423
185
  ```
424
186
 
425
- ### npm 构建
187
+ 顺序约束：`removeThematicBreaks` 在标题处理前；`numberTables` 在 Mermaid 前；`renderMermaid` 在 `numberPictures` 前。
426
188
 
427
- ```bash
428
- bun run build
429
- ```
189
+ ---
430
190
 
431
- 输出：
191
+ ## 中间文件
432
192
 
433
- ```text
434
- dist/
435
- ├── index.js
436
- └── index_bg.wasm
437
193
  ```
438
-
439
- 依赖会打包进 `index.js`，resvg WASM 作为相邻资源输出。`prepack` 会自动执行此构建。
440
-
441
- ### Windows 可执行文件
442
-
443
- ```bash
444
- bun run build:exe
194
+ ~/.md2docx/
195
+ ├── settings.json + presets/ # 持久数据，clean 保留
196
+ ├── preprocess/<basename>-<hash:12>/ # 预处理 Markdown + Mermaid PNG
197
+ ├── resources/default/*.json + *.lua # 物化的内置资源
198
+ └── style/<hash:16>.docx # reference DOCX 缓存
445
199
  ```
446
200
 
447
- Windows 输出为 `dist/md2docx.exe`。
448
-
449
- `build` 和 `build:exe` 都会先删除整个 `dist/`，因此两种产物不会同时保留。尤其不要依赖手工生成的 EXE 参与 `npm publish`：发布时 `prepack` 会重新生成 npm 所需的 `index.js` 和 WASM。
201
+ 预处理目录使用输入路径 SHA-256 前 12 位，同名文件在不同目录下隔离。
450
202
 
451
- ## 常见问题
203
+ ---
452
204
 
453
- ### 找不到 Pandoc
205
+ ## 构建
454
206
 
455
- 先检查：
207
+ 需要 [Bun](https://bun.sh/)。
456
208
 
457
209
  ```bash
458
- pandoc --version
210
+ git clone https://github.com/WXY-V1hZ/md2docx.git && cd md2docx
211
+ bun install
212
+ bun run src/index.ts report.md # 从源码运行
213
+ bun test # 全部测试
214
+ bun check # tsc + oxlint + oxfmt
215
+ bun run build # npm 构建 → dist/index.js + WASM
216
+ bun run build:exe # Windows 单文件 → dist/md2docx.exe
459
217
  ```
460
218
 
461
- 如果命令不存在，请从 [Pandoc 官方安装页](https://pandoc.org/installing.html) 安装，并重新打开终端使 `PATH` 生效。
462
-
463
- ### 从其他目录转换时图片缺失
219
+ ---
464
220
 
465
- 相对图片路径应以原始 Markdown 文件为基准：
221
+ ## 常见问题
466
222
 
467
- ```text
468
- docs/
469
- ├── example.md
470
- └── pictures/
471
- └── test.png
472
- ```
223
+ **找不到 Pandoc** — 确认 `pandoc --version` 可用，从 [pandoc.org](https://pandoc.org/installing.html) 安装并重启终端。
473
224
 
474
- ```markdown
475
- ![](./pictures/test.png)
476
- ```
225
+ **跨目录转换图片缺失** — 相对路径以原始 Markdown 文件为基准解析。检查路径大小写、文件存在性和 URL 编码。
477
226
 
478
- 新版会把原始文档目录和命令运行目录传给 Pandoc 的 `--resource-path`，并优先搜索原始文档目录。如果仍然缺图，请检查路径大小写、文件是否存在，以及图片语法中是否包含错误的 URL 编码。
227
+ ---
479
228
 
480
229
  ## 许可
481
230
 
482
- md2docx 以 [GNU GPL v3.0](LICENSE) 发布。
231
+ [GNU GPL v3.0](LICENSE)