@v1hz/md2docx 2.4.0 → 2.6.0

package/README.md

@@ -26,11 +26,16 @@
 | 图片尺寸限制      | 按自然尺寸等比缩小超过最大宽度或高度的图片                       |
 | Mermaid 图表      | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG |
 | Word 样式         | 支持受控语义化配置和完整底层样式，也可从现有 DOCX 提取样式       |
+| 配置预设          | 将处理配置和两层 Word 样式保存为可切换、可继承默认值的预设       |
 | Markdown 格式化   | 可只运行预处理流水线，输出格式化后的 Markdown                    |
 | 去除分隔符        | 默认移除 `---`、`***`、`___` 等分隔符行，减少无用页面间距        |
 | 集中缓存          | 中间文件统一存储到 `~/.md2docx/`，不会在当前目录创建 `tmp/`      |
 | Node 与可执行版本 | 支持 npm CLI，也支持构建不依赖 Node.js/Bun 的 Windows 可执行文件 |
 
+## AI 辅助
+
+本仓库提供 [`SKILL.md`](SKILL.md)，是供 AI 代码助手（如 Zed、Cursor、GitHub Copilot）使用的技能描述文件。在 AI 对话中引用此文件，AI 就能正确使用 `md2docx` CLI 完成转换、格式化、样式定制和导出等操作。
+
 ## 安装方式
 
 ### npm CLI
@@ -64,6 +69,10 @@ md2docx --file report.md --output output/report.docx
 # 使用自定义配置、底层样式和语义化样式配置
 md2docx -f report.md -c config.json --style-raw style-raw.json --style-config style-config.json
 
+# 保存并使用预设
+md2docx preset save --name academic --config config.json --style-config style-config.json
+md2docx preset use academic
+
 # 只执行 Markdown 预处理
 md2docx format -f report.md
 
@@ -90,6 +99,9 @@ md2docx format -f <markdown> [选项]
 md2docx export config [选项]
 md2docx export style-raw [选项]
 md2docx export style-config [选项]
+md2docx preset list
+md2docx preset use <name>
+md2docx preset save --name <name> [配置选项]
 md2docx clean
 ```
 
@@ -99,6 +111,7 @@ md2docx clean
 | ----------------------- | ---------------------------------------- |
 | `<markdown>`            | 位置参数；仅在没有其他转换选项时允许使用 |
 | `-f, --file <path>`     | Markdown 输入文件                        |
+| `--preset <name>`       | 本次转换使用指定预设                     |
 | `-c, --config <path>`   | 自定义配置 JSON                          |
 | `--style-raw <path>`    | 完整底层 Word 样式 JSON                  |
 | `--style-config <path>` | 受控语义化样式配置 JSON                  |
@@ -106,7 +119,7 @@ md2docx clean
 | `-h, --help`            | 显示帮助                                 |
 | `-v, --version`         | 显示版本号                               |
 
-位置参数不能和 `--file`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
+位置参数不能和 `--file`、`--preset`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
 
 ```bash
 md2docx report.md                 # 正确
@@ -121,6 +134,7 @@ md2docx -f report.md -o report.docx # 正确
 | 参数                  | 说明                                        |
 | --------------------- | ------------------------------------------- |
 | `-f, --file <path>`   | 必填，Markdown 输入文件                     |
+| `--preset <name>`     | 使用预设中的 `config.json`                  |
 | `-c, --config <path>` | 自定义配置 JSON                             |
 | `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
 
@@ -134,13 +148,27 @@ md2docx export style-config [-o style-config.json]
 
 `export config` 导出内置 Markdown 处理配置。`export style-raw` 不带 `--file` 时导出内置底层 Word 样式；指定 DOCX 时从该文档提取底层样式。`export style-config` 导出默认语义化样式配置。
 
+### preset
+
+```bash
+md2docx preset list
+md2docx preset use academic
+md2docx preset use default
+md2docx preset save --name academic \
+  --config config.json \
+  --style-raw style-raw.json \
+  --style-config style-config.json
+```
+
+用户预设位于 `~/.md2docx/presets/<name>/`，其中三个标准 JSON 文件都可省略；缺失项逐一继承系统内置 `default`。文件存在但内容无效时会报错。`preset save` 至少需要一个配置文件，同名保存会完整替换旧预设，未提供的类型改为继承默认值。`--preset` 只影响本次执行，`preset use` 会持久化默认选择。
+
 ### clean
 
 ```bash
 md2docx clean
 ```
 
-`clean` 只允许删除当前用户主目录下严格匹配的 `~/.md2docx/`。如果目标是符号链接，只删除链接本身。命令可重复执行；目录不存在时正常退出。
+`clean` 只删除 `~/.md2docx/` 下可重建的预处理文件、物化资源和样式缓存，保留 `presets/` 与 `settings.json`。命令拒绝跟随符号链接，且可重复执行。
 
 npm 卸载不会可靠地清理用户数据。卸载前如需清理，请显式运行：
 
@@ -167,14 +195,21 @@ md2docx export style-config               → ./style-config.json
 
 ```text
 ~/.md2docx/
+├── settings.json
+├── presets/
+│   └── <预设名称>/
+│       ├── config.json（可选）
+│       ├── style-raw.json（可选）
+│       └── style-config.json（可选）
 ├── preprocess/
 │   └── <输入文件名>-<绝对路径哈希>/
 │       ├── <输入文件名>_formatted.md
 │       └── mermaid_*.png
 ├── resources/
-│   ├── config.json
-│   ├── style-config.json
-│   ├── style-raw.json
+│   ├── default/
+│   │   ├── config.json
+│   │   ├── style-config.json
+│   │   └── style-raw.json
 │   ├── add-inline-code.lua
 │   └── limit-image-size.lua
 └── style/
@@ -189,7 +224,7 @@ md2docx export style-config               → ./style-config.json
 
 ## 配置
 
-内置配置来自 `config/config.json`，并由 `config/config.schema.json` 提供 JSON Schema。推荐先导出再编辑：
+内置配置来自 `config/default/config.json`，并由 `config/config.schema.json` 提供 JSON Schema。推荐先导出再编辑：
 
 ```bash
 md2docx export config
@@ -216,8 +251,8 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 | `renderMermaid.theme`            | beautiful-mermaid 主题                         | `"tokyo-night-light"` |
 | `renderMermaid.density`          | PNG 输出 DPI，最小值 72                        | `200`                 |
 | `imageSize.enabled`              | 等比缩小超过尺寸限制的图片                     | `true`                |
-| `imageSize.maxWidthCm`           | DOCX 图片最大宽度（厘米）                      | `15.5`                |
-| `imageSize.maxHeightCm`          | DOCX 图片最大高度（厘米）                      | `22`                  |
+| `imageSize.maxWidthCm`           | DOCX 图片最大宽度（厘米）                      | `12`                  |
+| `imageSize.maxHeightCm`          | DOCX 图片最大高度（厘米）                      | `12`                  |
 | `removeThematicBreaks.enabled`   | 移除 `---`、`***`、`___` 等分隔符行            | `true`                |
 
 图片尺寸限制在 Pandoc 生成 DOCX 前通过 Lua filter 应用。程序读取图片像素尺寸和 DPI，仅缩小超限图片，不会放大小图；宽度和高度使用同一缩放比例。Markdown 中已经显式设置 `width` 或 `height` 的图片视为用户覆盖，不应用全局限制。单张图片无法读取尺寸时会输出警告并继续转换。
@@ -226,7 +261,7 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 
 普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
 
-仓库中的 `config/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。完整底层 Word 样式位于 `config/style-raw.json`。
+仓库中的 `config/default/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。完整底层 Word 样式位于 `config/default/style-raw.json`。
 
 ```json
 {
@@ -234,11 +269,32 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
   "schemaVersion": 1,
   "options": {
     "body": {
-      "firstLineIndent": false
+      "firstLineIndent": false,
+      "lineSpacing": "onePointFive"
     },
     "headings": {
       "1": {
-        "startOnNewPage": false
+        "startOnNewPage": false,
+        "alignment": "left",
+        "bold": true
+      },
+      "2": {
+        "bold": true
+      },
+      "3": {
+        "bold": true
+      },
+      "4": {
+        "bold": true,
+        "italic": false
+      },
+      "5": {
+        "bold": true,
+        "italic": false
+      },
+      "6": {
+        "bold": true,
+        "italic": false
       }
     },
     "inlineCode": {
@@ -257,15 +313,15 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 md2docx -f report.md --style-config style-config.json
 ```
 
-字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。当前只开放正文首行缩进、一级标题另起一页、行内代码背景和代码块外框。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。正文行距为浮点数倍数，例如 `1.5` 表示 1.5 倍行距；一级标题对齐只接受 `left`、`center`。当前还开放一至六级标题粗体，以及四至六级标题斜体。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
 
 转换时按以下规则选择输入：
 
 | 参数                | 行为                                |
 | ------------------- | ----------------------------------- |
-| 都不指定            | 默认 raw + 默认 config              |
+| 都不指定            | 当前预设 raw + 当前预设 config      |
 | 仅 `--style-raw`    | 直接使用用户 raw，不应用默认 config |
-| 仅 `--style-config` | 用户 config 应用到默认 raw          |
+| 仅 `--style-config` | 用户 config 应用到当前预设 raw      |
 | 两者都指定          | 用户 config 应用到用户 raw          |
 
 最终有效的底层样式用于生成 reference DOCX，并通过 Pandoc 的 `--reference-doc` 应用。`--style-raw` 和 `--style-config` 类型固定，不能互换。

package/config/config.schema.json

@@ -131,13 +131,13 @@
           "description": "图片最大宽度（厘米）",
           "type": "number",
           "exclusiveMinimum": 0,
-          "default": 15.5
+          "default": 12
         },
         "maxHeightCm": {
           "description": "图片最大高度（厘米）",
           "type": "number",
           "exclusiveMinimum": 0,
-          "default": 22
+          "default": 12
         }
       },
       "required": ["enabled", "maxWidthCm", "maxHeightCm"]

package/config/default/style-config.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "options": {
+    "body": {
+      "firstLineIndent": true,
+      "lineSpacing": 1.5
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false,
+        "alignment": "left",
+        "bold": true
+      },
+      "2": {
+        "bold": true
+      },
+      "3": {
+        "bold": true
+      },
+      "4": {
+        "bold": true,
+        "italic": false
+      },
+      "5": {
+        "bold": true,
+        "italic": false
+      },
+      "6": {
+        "bold": true,
+        "italic": false
+      }
+    },
+    "inlineCode": {
+      "background": true
+    },
+    "codeBlock": {
+      "border": true
+    }
+  }
+}

package/config/style-config.schema.json

@@ -23,6 +23,11 @@
             "firstLineIndent": {
               "type": "boolean",
               "description": "正文是否使用预设的首行缩进"
+            },
+            "lineSpacing": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "description": "正文行距倍数，如 1.5 表示 1.5 倍行距"
             }
           }
         },
@@ -37,8 +42,32 @@
                 "startOnNewPage": {
                   "type": "boolean",
                   "description": "一级标题是否另起一页"
+                },
+                "alignment": {
+                  "type": "string",
+                  "enum": ["left", "center"],
+                  "description": "一级标题左对齐或居中"
+                },
+                "bold": {
+                  "type": "boolean",
+                  "description": "一级标题是否加粗"
                 }
               }
+            },
+            "2": {
+              "$ref": "#/$defs/headingBold"
+            },
+            "3": {
+              "$ref": "#/$defs/headingBold"
+            },
+            "4": {
+              "$ref": "#/$defs/headingBoldItalic"
+            },
+            "5": {
+              "$ref": "#/$defs/headingBoldItalic"
+            },
+            "6": {
+              "$ref": "#/$defs/headingBoldItalic"
             }
           }
         },
@@ -64,5 +93,31 @@
         }
       }
     }
+  },
+  "$defs": {
+    "headingBold": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "bold": {
+          "type": "boolean",
+          "description": "标题是否加粗"
+        }
+      }
+    },
+    "headingBoldItalic": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "bold": {
+          "type": "boolean",
+          "description": "标题是否加粗"
+        },
+        "italic": {
+          "type": "boolean",
+          "description": "标题是否斜体"
+        }
+      }
+    }
   }
 }