@v1hz/md2docx 2.2.0 → 2.4.0

package/README.md

@@ -17,18 +17,19 @@
 
 ## 功能
 
-| 功能              | 说明                                                               |
-| ----------------- | ------------------------------------------------------------------ |
-| 文档标题          | 从 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 的 Windows 可执行文件   |
+| 功能              | 说明                                                             |
+| ----------------- | ---------------------------------------------------------------- |
+| 文档标题          | 从 YAML frontmatter、H1 或文件名提取标题                         |
+| 标题层级归一化    | 将最浅标题归一化为 H1，并修复标题层级跳跃                        |
+| 标题编号          | 生成 `1`、`1.1`、`1.1.1` 等编号，并可剥离常见的已有中英文编号    |
+| 表格与图片编号    | 自动生成“表 1”“图 1：标题”等题注                                 |
+| 图片尺寸限制      | 按自然尺寸等比缩小超过最大宽度或高度的图片                       |
+| Mermaid 图表      | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG |
+| Word 样式         | 支持受控语义化配置和完整底层样式，也可从现有 DOCX 提取样式       |
+| Markdown 格式化   | 可只运行预处理流水线，输出格式化后的 Markdown                    |
+| 去除分隔符        | 默认移除 `---`、`***`、`___` 等分隔符行，减少无用页面间距        |
+| 集中缓存          | 中间文件统一存储到 `~/.md2docx/`，不会在当前目录创建 `tmp/`      |
+| Node 与可执行版本 | 支持 npm CLI，也支持构建不依赖 Node.js/Bun 的 Windows 可执行文件 |
 
 ## 安装方式
 
@@ -37,7 +38,7 @@
 前置依赖：
 
 - [Node.js 22.12+](https://nodejs.org/)
-- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用
+- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用；图片尺寸限制需要 Pandoc 3.1.13+
 
 ```bash
 npm install -g @v1hz/md2docx
@@ -58,26 +59,27 @@ npx @v1hz/md2docx report.md
 md2docx report.md
 
 # 使用任何转换选项时，输入必须通过 --file 指定
-md2docx --file report.md --output output/report.docx --force
+md2docx --file report.md --output output/report.docx
 
-# 使用自定义配置和样式
-md2docx -f report.md -c config.json -s style.json
+# 使用自定义配置、底层样式和语义化样式配置
+md2docx -f report.md -c config.json --style-raw style-raw.json --style-config style-config.json
 
 # 只执行 Markdown 预处理
 md2docx format -f report.md
 
-# 导出内置默认配置和样式
+# 导出内置默认配置、底层样式和语义化样式配置
 md2docx export config
-md2docx export style
+md2docx export style-raw
+md2docx export style-config
 
 # 从现有 DOCX 提取样式
-md2docx export style -f template.docx
+md2docx export style-raw -f template.docx
 
 # 删除 ~/.md2docx 中的中间文件和缓存
 md2docx clean
 ```
 
-所有写文件命令默认拒绝覆盖已有文件。确认覆盖时显式传入 `--force`。
+所有写文件命令默认覆盖已有输出。
 
 ## CLI 参考
 
@@ -86,29 +88,30 @@ md2docx <markdown>
 md2docx -f <markdown> [转换选项]
 md2docx format -f <markdown> [选项]
 md2docx export config [选项]
-md2docx export style [选项]
+md2docx export style-raw [选项]
+md2docx export style-config [选项]
 md2docx clean
 ```
 
 ### 转换
 
-| 参数                  | 说明                                     |
-| --------------------- | ---------------------------------------- |
-| `<markdown>`          | 位置参数；仅在没有其他转换选项时允许使用 |
-| `-f, --file <path>`   | Markdown 输入文件                        |
-| `-c, --config <path>` | 自定义配置 JSON                          |
-| `-s, --style <path>`  | 自定义样式 JSON                          |
-| `-o, --output <path>` | DOCX 输出路径                            |
-| `--force`             | 覆盖已有输出                             |
-| `-h, --help`          | 显示帮助                                 |
-| `-v, --version`       | 显示版本号                               |
+| 参数                    | 说明                                     |
+| ----------------------- | ---------------------------------------- |
+| `<markdown>`            | 位置参数；仅在没有其他转换选项时允许使用 |
+| `-f, --file <path>`     | Markdown 输入文件                        |
+| `-c, --config <path>`   | 自定义配置 JSON                          |
+| `--style-raw <path>`    | 完整底层 Word 样式 JSON                  |
+| `--style-config <path>` | 受控语义化样式配置 JSON                  |
+| `-o, --output <path>`   | DOCX 输出路径                            |
+| `-h, --help`            | 显示帮助                                 |
+| `-v, --version`         | 显示版本号                               |
 
-位置参数不能和 `--file`、`--config`、`--style`、`--output` 或 `--force` 混用。例如：
+位置参数不能和 `--file`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
 
 ```bash
 md2docx report.md                 # 正确
-md2docx report.md --force         # 错误
-md2docx -f report.md --force      # 正确
+md2docx report.md -o report.docx  # 错误
+md2docx -f report.md -o report.docx # 正确
 ```
 
 ### format
@@ -120,16 +123,16 @@ md2docx -f report.md --force      # 正确
 | `-f, --file <path>`   | 必填，Markdown 输入文件                     |
 | `-c, --config <path>` | 自定义配置 JSON                             |
 | `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
-| `--force`             | 覆盖已有输出                                |
 
 ### export
 
 ```bash
-md2docx export config [-o config.json] [--force]
-md2docx export style [-f template.docx] [-o style.json] [--force]
+md2docx export config [-o config.json]
+md2docx export style-raw [-f template.docx] [-o style-raw.json]
+md2docx export style-config [-o style-config.json]
 ```
 
-`export config` 导出内置默认配置。`export style` 不带 `--file` 时导出内置默认样式；指定 DOCX 时从该文档提取样式。
+`export config` 导出内置 Markdown 处理配置。`export style-raw` 不带 `--file` 时导出内置底层 Word 样式；指定 DOCX 时从该文档提取底层样式。`export style-config` 导出默认语义化样式配置。
 
 ### clean
 
@@ -153,8 +156,9 @@ 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
+md2docx export style-raw                  → ./style-raw.json
+md2docx export style-raw -f template.docx → ./template_style-raw.json
+md2docx export style-config               → ./style-config.json
 ```
 
 ## 中间文件与缓存
@@ -169,8 +173,10 @@ md2docx export style -f template.docx → ./template_style.json
 │       └── mermaid_*.png
 ├── resources/
 │   ├── config.json
-│   ├── style.json
-│   └── add-inline-code.lua
+│   ├── style-config.json
+│   ├── style-raw.json
+│   ├── add-inline-code.lua
+│   └── limit-image-size.lua
 └── style/
     └── <样式内容哈希>.docx
 ```
@@ -209,20 +215,69 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 | `renderMermaid.enabled`          | 将 Mermaid 渲染为 PNG                          | `true`                |
 | `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`                  |
 | `removeThematicBreaks.enabled`   | 移除 `---`、`***`、`___` 等分隔符行            | `true`                |
 
+图片尺寸限制在 Pandoc 生成 DOCX 前通过 Lua filter 应用。程序读取图片像素尺寸和 DPI，仅缩小超限图片，不会放大小图；宽度和高度使用同一缩放比例。Markdown 中已经显式设置 `width` 或 `height` 的图片视为用户覆盖，不应用全局限制。单张图片无法读取尺寸时会输出警告并继续转换。
+
 ## 样式定制
 
-`config/style.json` 定义 DOCX 的默认样式、标题样式、段落样式和字符样式。转换时，项目用 `docx` 生成 reference DOCX，再通过 Pandoc 的 `--reference-doc` 应用样式。
+普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
+
+仓库中的 `config/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。完整底层 Word 样式位于 `config/style-raw.json`。
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "options": {
+    "body": {
+      "firstLineIndent": false
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false
+      }
+    },
+    "inlineCode": {
+      "background": false
+    },
+    "codeBlock": {
+      "border": false
+    }
+  }
+}
+```
+
+将配置保存为 `style-config.json` 后使用：
+
+```bash
+md2docx -f report.md --style-config style-config.json
+```
+
+字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。当前只开放正文首行缩进、一级标题另起一页、行内代码背景和代码块外框。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+
+转换时按以下规则选择输入：
+
+| 参数                | 行为                                |
+| ------------------- | ----------------------------------- |
+| 都不指定            | 默认 raw + 默认 config              |
+| 仅 `--style-raw`    | 直接使用用户 raw，不应用默认 config |
+| 仅 `--style-config` | 用户 config 应用到默认 raw          |
+| 两者都指定          | 用户 config 应用到用户 raw          |
+
+最终有效的底层样式用于生成 reference DOCX，并通过 Pandoc 的 `--reference-doc` 应用。`--style-raw` 和 `--style-config` 类型固定，不能互换。
 
 ### 从现有 DOCX 提取
 
 ```bash
-md2docx export style -f template.docx
-md2docx -f report.md -s template_style.json
+md2docx export style-raw -f template.docx
+md2docx -f report.md --style-raw template_style-raw.json
 ```
 
-### 手动维护
+### 高级手动维护
 
 主要区域包括：
 
@@ -286,7 +341,7 @@ numberPictures()
     ↓
 生成或复用 reference DOCX
     ↓
-Pandoc + Lua filter
+Pandoc + 行内代码/图片尺寸 Lua filter
     ↓
 DOCX
 ```
@@ -349,14 +404,6 @@ pandoc --version
 
 如果命令不存在，请从 [Pandoc 官方安装页](https://pandoc.org/installing.html) 安装，并重新打开终端使 `PATH` 生效。
 
-### 输出文件已存在
-
-默认不会覆盖文件。确认目标可以覆盖后使用：
-
-```bash
-md2docx -f report.md --force
-```
-
 ### 从其他目录转换时图片缺失
 
 相对图片路径应以原始 Markdown 文件为基准：

package/config/config.json

@@ -23,6 +23,11 @@
     "theme": "tokyo-night-light",
     "density": 200
   },
+  "imageSize": {
+    "enabled": true,
+    "maxWidthCm": 12,
+    "maxHeightCm": 12
+  },
   "detectTitle": {
     "enabled": true,
     "strategy": "first-h1"

package/config/config.schema.json

@@ -117,6 +117,31 @@
       },
       "required": ["enabled", "theme", "density"]
     },
+    "imageSize": {
+      "description": "DOCX 图片尺寸限制",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "按图片自然尺寸等比缩小超限图片",
+          "type": "boolean",
+          "default": true
+        },
+        "maxWidthCm": {
+          "description": "图片最大宽度（厘米）",
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 15.5
+        },
+        "maxHeightCm": {
+          "description": "图片最大高度（厘米）",
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 22
+        }
+      },
+      "required": ["enabled", "maxWidthCm", "maxHeightCm"]
+    },
     "detectTitle": {
       "description": "文档标题",
       "type": "object",
@@ -162,6 +187,7 @@
     "normalizeHeadings",
     "numberHeadings",
     "renderMermaid",
+    "imageSize",
     "detectTitle",
     "removeThematicBreaks"
   ]

package/config/lua/limit-image-size.lua

@@ -0,0 +1,93 @@
+local max_width_cm
+local max_height_cm
+local size_cache = {}
+local warned = {}
+
+local function warn_once(source, message)
+  if warned[source] then
+    return
+  end
+  warned[source] = true
+  local text = "无法限制图片尺寸 " .. source .. "：" .. message
+  if pandoc.log and pandoc.log.warn then
+    pandoc.log.warn(text)
+  else
+    io.stderr:write("[WARNING] " .. text .. "\n")
+  end
+end
+
+local function metadata_number(meta, key)
+  local value = meta[key]
+  if value == nil then
+    return nil
+  end
+  return tonumber(pandoc.utils.stringify(value))
+end
+
+local function read_config(meta)
+  max_width_cm = metadata_number(meta, "md2docx-image-max-width-cm")
+  max_height_cm = metadata_number(meta, "md2docx-image-max-height-cm")
+end
+
+local function image_size(source)
+  local cached = size_cache[source]
+  if cached ~= nil then
+    return cached or nil
+  end
+  if pandoc.image == nil or pandoc.image.size == nil then
+    warn_once(source, "当前 Pandoc 不支持 pandoc.image.size，请升级到 3.1.13 或更高版本")
+    size_cache[source] = false
+    return nil
+  end
+
+  local fetched, _, contents = pcall(pandoc.mediabag.fetch, source)
+  if not fetched or contents == nil then
+    warn_once(source, fetched and "未读取到图片内容" or tostring(_))
+    size_cache[source] = false
+    return nil
+  end
+
+  local measured, size = pcall(pandoc.image.size, contents, PANDOC_WRITER_OPTIONS)
+  if not measured then
+    warn_once(source, tostring(size))
+    size_cache[source] = false
+    return nil
+  end
+
+  size_cache[source] = size
+  return size
+end
+
+local function limit_image(image)
+  if max_width_cm == nil or max_height_cm == nil then
+    return nil
+  end
+  if image.attributes.width ~= nil or image.attributes.height ~= nil then
+    return nil
+  end
+
+  local size = image_size(image.src)
+  if size == nil then
+    return nil
+  end
+
+  local fallback_dpi = PANDOC_WRITER_OPTIONS.dpi or 96
+  local horizontal_dpi = size.dpi_horz > 0 and size.dpi_horz or fallback_dpi
+  local vertical_dpi = size.dpi_vert > 0 and size.dpi_vert or fallback_dpi
+  local width_cm = size.width / horizontal_dpi * 2.54
+  local height_cm = size.height / vertical_dpi * 2.54
+  local scale = math.min(1, max_width_cm / width_cm, max_height_cm / height_cm)
+
+  if scale >= 1 then
+    return nil
+  end
+
+  image.attributes.width = string.format("%.4fcm", width_cm * scale)
+  image.attributes.height = string.format("%.4fcm", height_cm * scale)
+  return image
+end
+
+return {
+  { Meta = read_config },
+  { Image = limit_image },
+}

package/config/style-config.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "options": {
+    "body": {
+      "firstLineIndent": true
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false
+      }
+    },
+    "inlineCode": {
+      "background": true
+    },
+    "codeBlock": {
+      "border": true
+    }
+  }
+}

package/config/style-config.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "title": "md2docx 语义化样式配置",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "body": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "firstLineIndent": {
+              "type": "boolean",
+              "description": "正文是否使用预设的首行缩进"
+            }
+          }
+        },
+        "headings": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "1": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "startOnNewPage": {
+                  "type": "boolean",
+                  "description": "一级标题是否另起一页"
+                }
+              }
+            }
+          }
+        },
+        "inlineCode": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "background": {
+              "type": "boolean",
+              "description": "行内代码是否使用预设背景"
+            }
+          }
+        },
+        "codeBlock": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "border": {
+              "type": "boolean",
+              "description": "代码块是否使用预设外框"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/config/{style.json → style-raw.json}

@@ -559,7 +559,7 @@
           "eastAsia": "zh-CN"
         },
         "shading": {
-          "val": "pct5",
+          "type": "pct5",
           "color": "auto",
           "fill": "auto"
         }
@@ -571,40 +571,40 @@
         },
         "wordWrap": false,
         "shading": {
-          "val": "clear",
+          "type": "clear",
           "color": "F3F4F4",
           "fill": "FFFFFF",
           "themeFill": "background1"
         },
         "border": {
           "top": {
-            "val": "single",
+            "style": "single",
             "color": "BFBFBF",
-            "sz": 8,
+            "size": 8,
             "space": 10,
             "themeColor": "background1",
             "themeShade": "BF"
           },
           "left": {
-            "val": "single",
+            "style": "single",
             "color": "BFBFBF",
-            "sz": 8,
+            "size": 8,
             "space": 10,
             "themeColor": "background1",
             "themeShade": "BF"
           },
           "bottom": {
-            "val": "single",
+            "style": "single",
             "color": "BFBFBF",
-            "sz": 8,
+            "size": 8,
             "space": 10,
             "themeColor": "background1",
             "themeShade": "BF"
           },
           "right": {
-            "val": "single",
+            "style": "single",
             "color": "BFBFBF",
-            "sz": 8,
+            "size": 8,
             "space": 10,
             "themeColor": "background1",
             "themeShade": "BF"
@@ -750,7 +750,7 @@
           "eastAsia": "zh-CN"
         },
         "shading": {
-          "val": "clear",
+          "type": "clear",
           "color": "F3F4F4",
           "fill": "FFFFFF",
           "themeFill": "background1"
@@ -844,16 +844,16 @@
           "eastAsia": "zh-CN"
         },
         "shading": {
-          "val": "clear",
+          "type": "clear",
           "color": "F3F4F4",
           "fill": "F2F2F2",
           "themeFill": "background1",
           "themeFillShade": "F2"
         },
         "border": {
-          "val": "none",
+          "style": "none",
           "color": "auto",
-          "sz": 0,
+          "size": 0,
           "space": 0
         }
       }