@v1hz/md2docx 2.1.1 → 2.3.0

package/README.md

@@ -17,17 +17,18 @@
 
 ## 功能
 
-| 功能              | 说明                                                               |
-| ----------------- | ------------------------------------------------------------------ |
-| 文档标题          | 从 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 可执行文件 |
 
 ## 安装方式
 
@@ -96,7 +97,7 @@ md2docx clean
 | `<markdown>`          | 位置参数；仅在没有其他转换选项时允许使用 |
 | `-f, --file <path>`   | Markdown 输入文件                        |
 | `-c, --config <path>` | 自定义配置 JSON                          |
-| `-s, --style <path>`  | 自定义样式 JSON                          |
+| `-s, --style <path>`  | 语义化样式配置或完整底层样式 JSON        |
 | `-o, --output <path>` | DOCX 输出路径                            |
 | `--force`             | 覆盖已有输出                             |
 | `-h, --help`          | 显示帮助                                 |
@@ -168,6 +169,7 @@ md2docx export style -f template.docx → ./template_style.json
 │       └── mermaid_*.png
 ├── resources/
 │   ├── config.json
+│   ├── style-config.json
 │   ├── style.json
 │   └── add-inline-code.lua
 └── style/
@@ -208,10 +210,47 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 | `renderMermaid.enabled`          | 将 Mermaid 渲染为 PNG                          | `true`                |
 | `renderMermaid.theme`            | beautiful-mermaid 主题                         | `"tokyo-night-light"` |
 | `renderMermaid.density`          | PNG 输出 DPI，最小值 72                        | `200`                 |
+| `removeThematicBreaks.enabled`   | 移除 `---`、`***`、`___` 等分隔符行            | `true`                |
 
 ## 样式定制
 
-`config/style.json` 定义 DOCX 的默认样式、标题样式、段落样式和字符样式。转换时，项目用 `docx` 生成 reference DOCX，再通过 Pandoc 的 `--reference-doc` 应用样式。
+普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
+
+仓库中的 `config/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。未指定 `--style` 时，转换会自动加载内嵌的默认 `style-config.json`，再将它编译到内置底层样式；不需要手工传入 `-s`。
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "preset": "default",
+  "options": {
+    "body": {
+      "firstLineIndent": false
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false
+      }
+    },
+    "inlineCode": {
+      "background": false
+    },
+    "codeBlock": {
+      "border": false
+    }
+  }
+}
+```
+
+将配置保存为 `style-config.json` 后使用：
+
+```bash
+md2docx -f report.md -s style-config.json
+```
+
+字段缺失表示继承预设；`true` 表示使用预设效果；`false` 表示显式关闭。当前只开放正文首行缩进、一级标题另起一页、行内代码背景和代码块外框。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+
+`config/style.json` 仍定义完整的底层 DOCX 样式，包括标题、段落、字符和表格样式。转换时，项目先将语义化配置编译到底层样式，再用 `docx` 生成 reference DOCX，最后通过 Pandoc 的 `--reference-doc` 应用样式。现有完整样式 JSON 可继续直接传给 `--style`。
 
 ### 从现有 DOCX 提取
 
@@ -220,7 +259,7 @@ md2docx export style -f template.docx
 md2docx -f report.md -s template_style.json
 ```
 
-### 手动维护
+### 高级手动维护
 
 主要区域包括：
 
@@ -268,6 +307,8 @@ Markdown
     ↓
 addTitle()
     ↓
+removeThematicBreaks()
+    ↓
 normalizeHeadings()
     ↓
 numberHeadings()
@@ -287,6 +328,7 @@ Pandoc + Lua filter
 DOCX
 ```
 
+`removeThematicBreaks()` 在标题处理之前执行，避免分隔符干扰文档结构。
 `numberTables()` 必须先于 Mermaid 渲染；`numberPictures()` 必须后于 Mermaid 渲染，这样 Mermaid 生成的图片也能获得图题。
 
 ## 构建

package/config/config.json

@@ -26,5 +26,8 @@
   "detectTitle": {
     "enabled": true,
     "strategy": "first-h1"
+  },
+  "removeThematicBreaks": {
+    "enabled": true
   }
 }

package/config/config.schema.json

@@ -141,6 +141,19 @@
         }
       },
       "required": ["enabled", "strategy"]
+    },
+    "removeThematicBreaks": {
+      "description": "分隔符",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动移除 markdown 中的分隔符（---, ***, ___）",
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": ["enabled"]
     }
   },
   "required": [
@@ -149,6 +162,7 @@
     "normalizeHeadings",
     "numberHeadings",
     "renderMermaid",
-    "detectTitle"
+    "detectTitle",
+    "removeThematicBreaks"
   ]
 }

package/config/style-config.json

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

package/config/style-config.schema.json

@@ -0,0 +1,71 @@
+{
+  "$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", "preset"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "preset": {
+      "const": "default"
+    },
+    "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

@@ -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
         }
       }

package/dist/index.js

@@ -103482,7 +103482,7 @@ Actual: ` + parser.attribValue);
     var options;
     var pureJsParser = true;
     var currentElement;
-    function validateOptions(userOptions) {
+    function validateOptions2(userOptions) {
       options = helper.copyOptions(userOptions);
       helper.ensureFlagExists("ignoreDeclaration", options);
       helper.ensureFlagExists("ignoreInstruction", options);
@@ -103730,7 +103730,7 @@ Actual: ` + parser.attribValue);
       var parser = pureJsParser ? sax.parser(true, {}) : parser = new expat.Parser("UTF-8");
       var result = {};
       currentElement = result;
-      options = validateOptions(userOptions);
+      options = validateOptions2(userOptions);
       if (pureJsParser) {
         parser.opt = { strictEntities: true };
         parser.onopentag = onStartElement;
@@ -103764,13 +103764,13 @@ Actual: ` + parser.attribValue);
   require_xml2json = /* @__PURE__ */ __commonJSMin((exports, module) => {
     var helper = require_options_helper();
     var xml2js = require_xml2js();
-    function validateOptions(userOptions) {
+    function validateOptions2(userOptions) {
       var options = helper.copyOptions(userOptions);
       helper.ensureSpacesExists(options);
       return options;
     }
     module.exports = function(xml, userOptions) {
-      var options = validateOptions(userOptions), js = xml2js(xml, options), json, parentKey = "compact" in options && options.compact ? "_parent" : "parent";
+      var options = validateOptions2(userOptions), js = xml2js(xml, options), json, parentKey = "compact" in options && options.compact ? "_parent" : "parent";
       if ("addParent" in options && options.addParent)
         json = JSON.stringify(js, function(k, v) {
           return k === parentKey ? "_" : v;
@@ -103784,7 +103784,7 @@ Actual: ` + parser.attribValue);
     var helper = require_options_helper();
     var isArray = require_array_helper().isArray;
     var currentElement, currentElementName;
-    function validateOptions(userOptions) {
+    function validateOptions2(userOptions) {
       var options = helper.copyOptions(userOptions);
       helper.ensureFlagExists("ignoreDeclaration", options);
       helper.ensureFlagExists("ignoreInstruction", options);
@@ -104064,7 +104064,7 @@ Actual: ` + parser.attribValue);
       return xml.join("");
     }
     module.exports = function(js, options) {
-      options = validateOptions(options);
+      options = validateOptions2(options);
       var xml = [];
       currentElement = js;
       currentElementName = "_root_";
@@ -128401,7 +128401,7 @@ import { fileURLToPath as fileURLToPath3 } from "node:url";
 // package.json
 var package_default = {
   name: "@v1hz/md2docx",
-  version: "2.1.1",
+  version: "2.3.0",
   description: "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
   keywords: [
     "converter",
@@ -128471,7 +128471,7 @@ var package_default = {
 // src/cli.ts
 function createProgram(version, actions) {
   const program2 = new Command;
-  program2.name("md2docx").description("将 Markdown 转换为 Word 文档").version(version, "-v, --version", "显示版本号").helpOption("-h, --help", "显示帮助").helpCommand(false).showHelpAfterError("使用 --help 查看帮助").showSuggestionAfterError().enablePositionalOptions().argument("[markdown]", "Markdown 文件（仅无其他转换选项时）").option("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("-s, --style <path>", "自定义样式文件").option("-o, --output <path>", "输出 DOCX 文件").option("--force", "覆盖已有文件").action(async function(markdown, options) {
+  program2.name("md2docx").description("将 Markdown 转换为 Word 文档").version(version, "-v, --version", "显示版本号").helpOption("-h, --help", "显示帮助").helpCommand(false).showHelpAfterError("使用 --help 查看帮助").showSuggestionAfterError().enablePositionalOptions().argument("[markdown]", "Markdown 文件（仅无其他转换选项时）").option("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("-s, --style <path>", "自定义底层样式或语义化样式配置").option("-o, --output <path>", "输出 DOCX 文件").option("--force", "覆盖已有文件").action(async function(markdown, options) {
     const hasAdditionalOptions = options.config !== undefined || options.style !== undefined || options.output !== undefined || options.force !== undefined;
     if (markdown !== undefined) {
       if (options.file !== undefined || hasAdditionalOptions) {
@@ -128595,6 +128595,7 @@ function validateConfig(value, path2) {
   if (!Number.isInteger(mermaid.density) || mermaid.density < 72) {
     invalidConfig(path2, "renderMermaid.density", "必须是不小于 72 的整数");
   }
+  validateEnabled(root.removeThematicBreaks, path2, "removeThematicBreaks");
   const title = expectRecord(root.detectTitle, path2, "detectTitle");
   expectBoolean(title.enabled, path2, "detectTitle.enabled");
   const strategy = expectString(title.strategy, path2, "detectTitle.strategy");
@@ -146041,6 +146042,11 @@ function expandHexColor(color2) {
   return color2.length === 4 ? `#${color2[1]}${color2[1]}${color2[2]}${color2[2]}${color2[3]}${color2[3]}` : color2;
 }
 
+// src/preprocess/thematic-break.ts
+function removeThematicBreaks(root2) {
+  root2.children = root2.children.filter((node2) => node2.type !== "thematicBreak");
+}
+
 // src/preprocess/index.ts
 async function preprocess2(mdPath, cfg, outDir, assetUrlDir = outDir) {
   const md = await readFile3(mdPath, "utf-8");
@@ -146051,6 +146057,9 @@ async function preprocess2(mdPath, cfg, outDir, assetUrlDir = outDir) {
     headings.push(heading2);
   });
   addTitle(mdPath, ast, headings, cfg.detectTitle);
+  if (cfg.removeThematicBreaks.enabled) {
+    removeThematicBreaks(ast);
+  }
   if (cfg.normalizeHeadings.enabled || cfg.numberHeadings.enabled) {
     normalizeHeadings(headings);
   }
@@ -146102,6 +146111,9 @@ var config_default = `{
   "detectTitle": {
     "enabled": true,
     "strategy": "first-h1"
+  },
+  "removeThematicBreaks": {
+    "enabled": true
   }
 }
 `;
@@ -146114,6 +146126,30 @@ function Code(el)
 end
 return { Code = Code }`;
 
+// config/style-config.json
+var style_config_default = `{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "preset": "default",
+  "options": {
+    "body": {
+      "firstLineIndent": true
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false
+      }
+    },
+    "inlineCode": {
+      "background": true
+    },
+    "codeBlock": {
+      "border": true
+    }
+  }
+}
+`;
+
 // config/style.json
 var style_default = `{
   "default": {
@@ -146676,7 +146712,7 @@ var style_default = `{
           "eastAsia": "zh-CN"
         },
         "shading": {
-          "val": "pct5",
+          "type": "pct5",
           "color": "auto",
           "fill": "auto"
         }
@@ -146688,40 +146724,40 @@ var style_default = `{
         },
         "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"
@@ -146867,7 +146903,7 @@ var style_default = `{
           "eastAsia": "zh-CN"
         },
         "shading": {
-          "val": "clear",
+          "type": "clear",
           "color": "F3F4F4",
           "fill": "FFFFFF",
           "themeFill": "background1"
@@ -146961,16 +146997,16 @@ var style_default = `{
           "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
         }
       }
@@ -147074,6 +147110,7 @@ var style_default = `{
 
 // src/resources.ts
 var DEFAULT_CONFIG_TEXT = config_default;
+var DEFAULT_STYLE_CONFIG_TEXT = style_config_default;
 var DEFAULT_STYLE_TEXT = style_default;
 function materializeResource(name2, content3) {
   const directory = join4(TMP_DIR, "resources");
@@ -147090,18 +147127,216 @@ function materializeDefaultConfig() {
 function materializeDefaultStyle() {
   return materializeResource("style.json", DEFAULT_STYLE_TEXT);
 }
+function materializeDefaultStyleConfig() {
+  materializeDefaultStyle();
+  return materializeResource("style-config.json", DEFAULT_STYLE_CONFIG_TEXT);
+}
 function materializeLuaFilter() {
   return materializeResource("add-inline-code.lua", add_inline_code_default);
 }
 
 // src/style/generate.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4 } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { createHash as createHash2 } from "node:crypto";
 import { dirname as dirname4 } from "path";
-async function generateTemplateDocx(styleJsonPath, outputPath) {
+
+// src/style/compiler.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+
+// src/style/config.ts
+function isStyleConfig(value2) {
+  if (!isRecord(value2))
+    return false;
+  return "schemaVersion" in value2 || "preset" in value2 || "options" in value2;
+}
+function validateStyleConfig(value2, path3) {
+  const root2 = expectRecord2(value2, path3, "样式配置");
+  rejectUnknown(root2, ["$schema", "schemaVersion", "preset", "options"], path3, "样式配置");
+  if (root2.$schema !== undefined)
+    expectString2(root2.$schema, path3, "$schema");
+  if (root2.schemaVersion !== 1)
+    invalidStyleConfig(path3, "schemaVersion", "目前只支持版本 1");
+  if (root2.preset !== "default")
+    invalidStyleConfig(path3, "preset", '目前只支持 "default"');
+  if (root2.options !== undefined)
+    validateOptions(root2.options, path3);
+  return root2;
+}
+function validateOptions(value2, path3) {
+  const options = expectRecord2(value2, path3, "options");
+  rejectUnknown(options, ["body", "headings", "inlineCode", "codeBlock"], path3, "options");
+  if (options.body !== undefined) {
+    const body = expectRecord2(options.body, path3, "options.body");
+    rejectUnknown(body, ["firstLineIndent"], path3, "options.body");
+    if (body.firstLineIndent !== undefined) {
+      expectBoolean2(body.firstLineIndent, path3, "options.body.firstLineIndent");
+    }
+  }
+  if (options.headings !== undefined) {
+    const headings = expectRecord2(options.headings, path3, "options.headings");
+    rejectUnknown(headings, ["1"], path3, "options.headings");
+    if (headings["1"] !== undefined) {
+      const heading1 = expectRecord2(headings["1"], path3, 'options.headings["1"]');
+      rejectUnknown(heading1, ["startOnNewPage"], path3, 'options.headings["1"]');
+      if (heading1.startOnNewPage !== undefined) {
+        expectBoolean2(heading1.startOnNewPage, path3, 'options.headings["1"].startOnNewPage');
+      }
+    }
+  }
+  if (options.inlineCode !== undefined) {
+    const inlineCode2 = expectRecord2(options.inlineCode, path3, "options.inlineCode");
+    rejectUnknown(inlineCode2, ["background"], path3, "options.inlineCode");
+    if (inlineCode2.background !== undefined) {
+      expectBoolean2(inlineCode2.background, path3, "options.inlineCode.background");
+    }
+  }
+  if (options.codeBlock !== undefined) {
+    const codeBlock = expectRecord2(options.codeBlock, path3, "options.codeBlock");
+    rejectUnknown(codeBlock, ["border"], path3, "options.codeBlock");
+    if (codeBlock.border !== undefined) {
+      expectBoolean2(codeBlock.border, path3, "options.codeBlock.border");
+    }
+  }
+}
+function rejectUnknown(value2, allowed, path3, field) {
+  const unknown2 = Object.keys(value2).find((key) => !allowed.includes(key));
+  if (unknown2 !== undefined)
+    invalidStyleConfig(path3, `${field}.${unknown2}`, "不是支持的配置项");
+}
+function expectRecord2(value2, path3, field) {
+  if (!isRecord(value2))
+    invalidStyleConfig(path3, field, "必须是对象");
+  return value2;
+}
+function isRecord(value2) {
+  return typeof value2 === "object" && value2 !== null && !Array.isArray(value2);
+}
+function expectBoolean2(value2, path3, field) {
+  if (typeof value2 !== "boolean")
+    invalidStyleConfig(path3, field, "必须是 boolean");
+}
+function expectString2(value2, path3, field) {
+  if (typeof value2 !== "string")
+    invalidStyleConfig(path3, field, "必须是字符串");
+}
+function invalidStyleConfig(path3, field, reason) {
+  throw new Error(`样式配置无效：${path3}
+位置：${field}
+原因：${reason}`);
+}
+
+// src/style/compiler.ts
+function loadEffectiveStyles(stylePath) {
+  const source = parseJson(readFileSync2(stylePath, "utf-8"), stylePath);
+  if (!isStyleConfig(source))
+    return expectStyleDefinition(source, stylePath);
+  const config = validateStyleConfig(source, stylePath);
+  const preset = expectStyleDefinition(parseJson(DEFAULT_STYLE_TEXT, "内置默认样式"), "内置默认样式");
+  return compileStyleConfig(preset, config);
+}
+function compileStyleConfig(preset, config) {
+  const styles = structuredClone(preset);
+  const options = config.options;
+  if (!options)
+    return styles;
+  const firstLineIndent = options.body?.firstLineIndent;
+  if (firstLineIndent !== undefined)
+    applyBodyFirstLineIndent(styles, firstLineIndent);
+  const startOnNewPage = options.headings?.["1"]?.startOnNewPage;
+  if (startOnNewPage !== undefined)
+    applyHeading1PageBreak(styles, startOnNewPage);
+  const inlineCodeBackground = options.inlineCode?.background;
+  if (inlineCodeBackground !== undefined) {
+    applyInlineCodeBackground(styles, inlineCodeBackground);
+  }
+  const codeBlockBorder = options.codeBlock?.border;
+  if (codeBlockBorder !== undefined)
+    applyCodeBlockBorder(styles, codeBlockBorder);
+  return styles;
+}
+function applyBodyFirstLineIndent(styles, enabled) {
+  const firstParagraph = findStyle(styles, "paragraphStyles", "First Paragraph");
+  const bodyText = findStyle(styles, "paragraphStyles", "Body Text");
+  for (const style of [firstParagraph, bodyText]) {
+    const paragraph2 = ensureObject(style, "paragraph");
+    paragraph2.indent = {
+      ...optionalObject(paragraph2.indent),
+      firstLine: enabled ? 200 : 0,
+      firstLineChars: enabled ? 200 : 0
+    };
+  }
+}
+function applyHeading1PageBreak(styles, enabled) {
+  const heading1 = findStyle(styles, "paragraphStyles", "heading 1");
+  ensureObject(heading1, "paragraph").pageBreakBefore = enabled;
+}
+function applyInlineCodeBackground(styles, enabled) {
+  const inlineCode2 = findStyle(styles, "characterStyles", "Inline Code");
+  ensureObject(inlineCode2, "run").shading = {
+    type: "clear",
+    color: enabled ? "F3F4F4" : "auto",
+    fill: enabled ? "F2F2F2" : "auto"
+  };
+}
+function applyCodeBlockBorder(styles, enabled) {
+  const sourceCode = findStyle(styles, "paragraphStyles", "Source Code");
+  const border = () => ({
+    style: enabled ? "single" : "none",
+    color: enabled ? "BFBFBF" : "auto",
+    size: enabled ? 8 : 0,
+    space: enabled ? 10 : 0
+  });
+  ensureObject(sourceCode, "paragraph").border = {
+    top: border(),
+    left: border(),
+    bottom: border(),
+    right: border()
+  };
+}
+function findStyle(styles, collectionName, name2) {
+  const collection = styles[collectionName];
+  if (!Array.isArray(collection)) {
+    throw new Error(`内置样式缺少 ${collectionName}，无法应用样式配置`);
+  }
+  const normalizedName = name2.toLowerCase();
+  const style = collection.find((entry) => isRecord2(entry) && typeof entry.name === "string" && entry.name.toLowerCase() === normalizedName);
+  if (!style)
+    throw new Error(`内置样式缺少“${name2}”，无法应用样式配置`);
+  return style;
+}
+function ensureObject(parent, key) {
+  const current = parent[key];
+  if (isRecord2(current))
+    return current;
+  const created = {};
+  parent[key] = created;
+  return created;
+}
+function optionalObject(value2) {
+  return isRecord2(value2) ? value2 : {};
+}
+function parseJson(text5, path3) {
+  try {
+    return JSON.parse(text5);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`样式文件不是有效的 JSON：${path3}
+${message}`);
+  }
+}
+function expectStyleDefinition(value2, path3) {
+  if (!isRecord2(value2))
+    throw new Error(`样式文件必须是 JSON 对象：${path3}`);
+  return value2;
+}
+function isRecord2(value2) {
+  return typeof value2 === "object" && value2 !== null && !Array.isArray(value2);
+}
+
+// src/style/generate.ts
+async function generateTemplateDocxFromStyles(raw, outputPath) {
   const { Document: Document2, Packer: Packer3 } = await Promise.resolve().then(() => (init_dist(), exports_dist));
-  const raw = JSON.parse(readFileSync2(styleJsonPath, "utf-8"));
   const tableStylesXml = raw.tableStylesXml;
   const { tableStylesXml: _, ...styles } = raw;
   const doc = new Document2({
@@ -147127,13 +147362,13 @@ async function generateTemplateDocx(styleJsonPath, outputPath) {
 }
 var generatePromises = new Map;
 async function ensureTemplateDocx(styleJsonPath) {
-  const raw = readFileSync2(styleJsonPath);
-  const hash = createHash2("sha256").update(raw).digest("hex").slice(0, 16);
+  const styles = loadEffectiveStyles(styleJsonPath);
+  const hash = createHash2("sha256").update(JSON.stringify(styles)).digest("hex").slice(0, 16);
   const outputPath = styleTemplateDocx(hash);
   if (!existsSync5(outputPath)) {
     let promise = generatePromises.get(outputPath);
     if (!promise) {
-      promise = generateTemplateDocx(styleJsonPath, outputPath).catch((error) => {
+      promise = generateTemplateDocxFromStyles(styles, outputPath).catch((error) => {
         generatePromises.delete(outputPath);
         throw error;
       });
@@ -147150,7 +147385,7 @@ async function convertMarkdown(options) {
     throw new Error("缺少必填参数：--file");
   const input = resolveInputPath(options.file, [".md", ".markdown"], "Markdown 文件");
   const configPath = options.config ? resolveInputPath(options.config, [".json"], "配置文件") : materializeDefaultConfig();
-  const stylePath = options.style ? resolveInputPath(options.style, [".json"], "样式文件") : materializeDefaultStyle();
+  const stylePath = options.style ? resolveInputPath(options.style, [".json"], "样式文件") : materializeDefaultStyleConfig();
   const baseName = parse4(input).name;
   const output = resolveOutputPath(options.output, `${baseName}.docx`, [".docx"], "DOCX 输出文件");
   prepareOutput(output, options.force ?? false);
@@ -147287,31 +147522,31 @@ function mapShd(shd) {
   if (!shd)
     return;
   const sh = {};
-  for (const a of [
-    "val",
-    "color",
-    "fill",
-    "themeColor",
-    "themeTint",
-    "themeFill",
-    "themeFillShade",
-    "themeShade"
-  ]) {
+  for (const a of ["color", "fill"]) {
     const v = wAttr(shd, a);
     if (v !== null)
       sh[a] = v;
   }
+  const type = wAttr(shd, "val");
+  if (type !== null)
+    sh.type = type;
   return Object.keys(sh).length > 0 ? sh : undefined;
 }
 function mapBorder(bdr) {
   if (!bdr)
     return;
   const b = {};
-  for (const a of ["val", "color", "sz", "space", "themeColor", "themeShade"]) {
+  for (const a of ["color", "space"]) {
     const v = wAttr(bdr, a);
     if (v !== null)
       b[a] = /^\d+$/.test(v) ? Number(v) : v;
   }
+  const style = wAttr(bdr, "val");
+  if (style !== null)
+    b.style = style;
+  const size = wAttr(bdr, "sz");
+  if (size !== null)
+    b.size = /^\d+$/.test(size) ? Number(size) : size;
   return Object.keys(b).length > 0 ? b : undefined;
 }
 function mapRunProps(rPr) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v1hz/md2docx",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
   "keywords": [
     "converter",