@v1hz/md2docx 1.1.0 → 1.3.0
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.
- package/LICENSE +11 -16
- package/README.md +106 -59
- package/package.json +3 -3
package/LICENSE
CHANGED
|
@@ -1,21 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
GNU General Public License v3.0
|
|
2
2
|
|
|
3
3
|
Copyright (c) 2025–2026 WXY-V1hZ
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
5
|
+
This program is free software: you can redistribute it and/or modify
|
|
6
|
+
it under the terms of the GNU General Public License as published by
|
|
7
|
+
the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
(at your option) any later version.
|
|
11
9
|
|
|
12
|
-
|
|
13
|
-
|
|
10
|
+
This program is distributed in the hope that it will be useful,
|
|
11
|
+
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
GNU General Public License for more details.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
15
|
+
You should have received a copy of the GNU General Public License
|
|
16
|
+
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
package/README.md
CHANGED
|
@@ -1,62 +1,67 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/logo.svg" alt="md2docx" width="160" height="160">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">md2docx</h1>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。
|
|
9
|
+
</p>
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://www.npmjs.com/package/@v1hz/md2docx"><img src="https://img.shields.io/npm/v/@v1hz/md2docx" alt="npm version"></a>
|
|
13
|
+
<a href="https://github.com/WXY-V1hZ/md2docx"><img src="https://img.shields.io/badge/license-GPL--3.0-blue" alt="license"></a>
|
|
14
|
+
</p>
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
- **标题层级归一化** — 自动修正标题层级跳跃，确保从 H1 开始连续递增
|
|
11
|
-
- **标题编号** — 为标题添加多级编号（1、1.1、1.1.1 …），支持剥离已有编号
|
|
12
|
-
- **表格编号** — 自动检测表格并添加"表 1"、"表 2"……编号
|
|
13
|
-
- **图片编号** — 为独立图片添加"图 1"、"图 2"……编号
|
|
14
|
-
- **Mermaid 图表** — 将 Mermaid 代码块渲染为 PNG 图片嵌入文档
|
|
15
|
-
- **Word 导出** — 集成 pandoc，一键生成 .docx 文件
|
|
16
|
+
---
|
|
16
17
|
|
|
17
|
-
##
|
|
18
|
-
|
|
19
|
-
### 前置依赖
|
|
18
|
+
## 功能
|
|
20
19
|
|
|
21
|
-
|
|
22
|
-
- [pandoc](https://pandoc.org)（可选，需导出 Word 时安装）
|
|
20
|
+
将 Markdown 转换为格式精美的 Word 文档，自动处理：
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
| 功能 | 说明 |
|
|
23
|
+
| ------------------ | ---------------------------------------------------------- |
|
|
24
|
+
| **文档标题** | 从 frontmatter、H1 或文件名自动提取 |
|
|
25
|
+
| **标题层级归一化** | 修正标题层级跳跃，确保从 H1 开始连续递增 |
|
|
26
|
+
| **标题编号** | 为标题添加多级编号（1、1.1、1.1.1 …），支持剥离已有编号 |
|
|
27
|
+
| **表格编号** | 自动为表格添加编号（表 1、表 2 …） |
|
|
28
|
+
| **图片编号** | 为独立图片添加编号（图 1、图 2 …） |
|
|
29
|
+
| **Mermaid 图表** | 将 Mermaid 代码块渲染为 PNG 图片 |
|
|
30
|
+
| **Word 导出** | 集成 pandoc，传入自定义样式模板，一键生成 .docx |
|
|
31
|
+
| **样式定制** | 通过 `style/style.json` 定义文档样式，支持从模板 docx 提取 |
|
|
32
|
+
| **web 配置编辑器** | 浏览器中可视化编辑配置 |
|
|
25
33
|
|
|
26
|
-
|
|
27
|
-
npx @v1hz/md2docx README.md
|
|
28
|
-
```
|
|
34
|
+
## 安装
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
**前置依赖**：[Bun](https://bun.sh) | [Pandoc](https://pandoc.org)
|
|
31
37
|
|
|
32
38
|
```bash
|
|
33
39
|
npm install -g @v1hz/md2docx
|
|
34
|
-
md2docx
|
|
40
|
+
md2docx docs/example.md
|
|
35
41
|
```
|
|
36
42
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
git clone https://github.com/WXY-V1hZ/md2docx.git
|
|
41
|
-
cd md2docx
|
|
42
|
-
bun install
|
|
43
|
-
bun run src/index.ts docs/example.md
|
|
44
|
-
```
|
|
43
|
+
也可通过 `npx @v1hz/md2docx` 直接运行。
|
|
45
44
|
|
|
46
45
|
## 快速开始
|
|
47
46
|
|
|
48
47
|
```bash
|
|
49
48
|
# 处理 Markdown 并生成 Word 文档
|
|
50
|
-
|
|
49
|
+
md2docx docs/example.md
|
|
51
50
|
|
|
52
51
|
# 只预处理，不调用 pandoc
|
|
53
|
-
|
|
52
|
+
md2docx docs/example.md --pandoc.enabled false
|
|
54
53
|
|
|
55
54
|
# 指定输出路径
|
|
56
|
-
|
|
55
|
+
md2docx docs/example.md -o output/example.docx
|
|
56
|
+
|
|
57
|
+
# 打开 web 网页自定义配置
|
|
58
|
+
md2docx --web
|
|
57
59
|
|
|
58
60
|
# 使用自定义配置文件
|
|
59
|
-
|
|
61
|
+
md2docx docs/example.md --config ./my-config.json
|
|
62
|
+
|
|
63
|
+
# 清除缓存（预处理中间产物、样式模板等）
|
|
64
|
+
md2docx clean
|
|
60
65
|
```
|
|
61
66
|
|
|
62
67
|
## 配置
|
|
@@ -66,64 +71,106 @@ npx @v1hz/md2docx docs/example.md --config ./my-config.json
|
|
|
66
71
|
所有配置项均可通过命令行覆盖：
|
|
67
72
|
|
|
68
73
|
```bash
|
|
69
|
-
|
|
74
|
+
md2docx docs/example.md --figureCaption.enabled false
|
|
70
75
|
```
|
|
71
76
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `numberHeadings.
|
|
80
|
-
| `figureCaption.enabled`
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
|
|
85
|
-
|
|
77
|
+
| 配置项 | 说明 | 默认值 |
|
|
78
|
+
| -------------------------------- | ------------------------------------------------------------ | --------------------- |
|
|
79
|
+
| `detectTitle.enabled` | 自动设置文档标题 | `true` |
|
|
80
|
+
| `detectTitle.strategy` | 标题来源策略：`first-h1` / `single-h1` / `filename` / `none` | `"first-h1"` |
|
|
81
|
+
| `normalizeHeadings.enabled` | 自动修正标题层级 | `true` |
|
|
82
|
+
| `numberHeadings.enabled` | 自动为标题编号（开启时自动启用 normalizeHeadings） | `true` |
|
|
83
|
+
| `numberHeadings.detectExisting` | 重新编号前移除已有编号 | `true` |
|
|
84
|
+
| `numberHeadings.useBuiltinRules` | 识别常见的中文和数字编号 | `true` |
|
|
85
|
+
| `figureCaption.enabled` | 自动为图片编号（格式：`图 {n}`） | `true` |
|
|
86
|
+
| `figureCaption.format` | 图片编号格式 | `"图 {n}"` |
|
|
87
|
+
| `figureCaption.separator` | 编号与标题之间的分隔符 | `"："` |
|
|
88
|
+
| `tableCaption.enabled` | 自动为表格编号（格式：`表 {n}`） | `true` |
|
|
89
|
+
| `tableCaption.format` | 表格编号格式 | `"表 {n}"` |
|
|
90
|
+
| `tableCaption.separator` | 编号与标题之间的分隔符 | `" "` |
|
|
91
|
+
| `renderMermaid.enabled` | 渲染 Mermaid 图表为 PNG | `true` |
|
|
92
|
+
| `renderMermaid.theme` | 图表主题 | `"tokyo-night-light"` |
|
|
93
|
+
| `renderMermaid.density` | 图片清晰度（DPI，最小 72） | `200` |
|
|
94
|
+
| `pandoc.enabled` | 生成 Word 文档 | `true` |
|
|
95
|
+
| `pandoc.outputName` | 输出文件名，`{file_name}` 代表源文件名 | `"{file_name}.docx"` |
|
|
96
|
+
|
|
97
|
+
## 样式定制
|
|
98
|
+
|
|
99
|
+
`style/style.json` 定义了 docx 输出的全部样式，包括字体、字号、颜色、缩进、间距等。
|
|
100
|
+
|
|
101
|
+
### 从模板 docx 提取样式
|
|
102
|
+
|
|
103
|
+
如果你有一个排版精美的 docx 模板，可以提取其样式：
|
|
86
104
|
|
|
87
105
|
```bash
|
|
88
|
-
bun run src/
|
|
106
|
+
bun run src/style/extract.ts
|
|
89
107
|
```
|
|
90
108
|
|
|
91
|
-
|
|
109
|
+
提取后修改 `style/style.json`，转换时会自动使用这些样式生成输出文档。
|
|
110
|
+
|
|
111
|
+
### 手动维护样式
|
|
112
|
+
|
|
113
|
+
也可直接编辑 `style/style.json`。支持以下样式配置：
|
|
114
|
+
|
|
115
|
+
- **文档默认样式**（`default.document`）：全局字体、字号、段落间距
|
|
116
|
+
- **内置样式覆盖**（`default.heading1` … `default.heading6`、`default.title` 等）
|
|
117
|
+
- **自定义段落样式**（`paragraphStyles`）
|
|
118
|
+
- **自定义字符样式**（`characterStyles`）
|
|
119
|
+
|
|
120
|
+
详细的样式字段定义参考 [docx 包文档](https://docx.js.org)。
|
|
92
121
|
|
|
93
122
|
## 处理流水线
|
|
94
123
|
|
|
124
|
+
项目遵循单向处理流水线，每个步骤职责单一。
|
|
125
|
+
|
|
95
126
|
```
|
|
96
127
|
Markdown
|
|
97
128
|
↓
|
|
98
129
|
解析 AST
|
|
99
130
|
↓
|
|
100
|
-
addTitle()
|
|
131
|
+
addTitle() ← 提取文档标题
|
|
101
132
|
↓
|
|
102
|
-
normalizeHeadings()
|
|
133
|
+
normalizeHeadings() ← 修正标题层级（最小深度 → H1，消除跳跃）
|
|
103
134
|
↓
|
|
104
|
-
numberHeadings()
|
|
135
|
+
numberHeadings() ← 添加标题编号（1 / 1.1 / 1.1.1 …）
|
|
105
136
|
↓
|
|
106
|
-
numberTables()
|
|
137
|
+
numberTables() ← 添加表格编号（表 1、表 2 …）
|
|
107
138
|
↓
|
|
108
|
-
renderMermaid()
|
|
139
|
+
renderMermaid() ← Mermaid 代码块 → PNG 图片
|
|
109
140
|
↓
|
|
110
|
-
numberPictures()
|
|
141
|
+
numberPictures() ← 添加图片编号（图 1、图 2 …）
|
|
111
142
|
↓
|
|
112
143
|
序列化 Markdown
|
|
113
144
|
↓
|
|
114
|
-
pandoc
|
|
145
|
+
生成样式模板 docx ← 根据 style/style.json 生成 pandoc reference-doc
|
|
146
|
+
↓
|
|
147
|
+
pandoc → DOCX ← 以 --reference-doc 传入样式模板
|
|
115
148
|
```
|
|
116
149
|
|
|
117
150
|
## 开发
|
|
118
151
|
|
|
152
|
+
### 从源码运行
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
git clone https://github.com/WXY-V1hZ/md2docx.git
|
|
156
|
+
cd md2docx
|
|
157
|
+
bun install
|
|
158
|
+
bun run src/index.ts docs/example.md
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### 命令
|
|
162
|
+
|
|
119
163
|
```bash
|
|
120
164
|
# 测试
|
|
121
165
|
bun test
|
|
122
166
|
|
|
123
167
|
# 类型检查 + 代码检查 + 格式检查
|
|
124
168
|
bun check
|
|
169
|
+
|
|
170
|
+
# 清除缓存
|
|
171
|
+
bun run src/index.ts clean
|
|
125
172
|
```
|
|
126
173
|
|
|
127
174
|
## 许可
|
|
128
175
|
|
|
129
|
-
本项目基于
|
|
176
|
+
本项目基于 GNU General Public License v3.0 开源 — 详见 [LICENSE](LICENSE)。
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@v1hz/md2docx",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "基于 pandoc 的 Markdown 转 Word
|
|
3
|
+
"version": "1.3.0",
|
|
4
|
+
"description": "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"converter",
|
|
7
7
|
"docx",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"bugs": {
|
|
15
15
|
"url": "https://github.com/WXY-V1hZ/md2docx/issues"
|
|
16
16
|
},
|
|
17
|
-
"license": "
|
|
17
|
+
"license": "GPL-3.0-only",
|
|
18
18
|
"author": "WXY-V1hZ",
|
|
19
19
|
"repository": {
|
|
20
20
|
"type": "git",
|