@v1hz/md2docx 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 WXY-V1hZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# md2docx
+
+基于 pandoc 的 Markdown 转 Word (.docx) 工具，在转换前执行 AST 变换以提升文档输出质量。
+
+## 功能
+
+将 Markdown 转换为格式精美的 Word 文档，自动处理：
+
+- **文档标题** — 从 frontmatter、H1 或文件名自动提取文档标题
+- **标题层级归一化** — 自动修正标题层级跳跃，确保从 H1 开始连续递增
+- **标题编号** — 为标题添加多级编号（1、1.1、1.1.1 …），支持剥离已有编号
+- **表格编号** — 自动检测表格并添加"表 1"、"表 2"……编号
+- **图片编号** — 为独立图片添加"图 1"、"图 2"……编号
+- **Mermaid 图表** — 将 Mermaid 代码块渲染为 PNG 图片嵌入文档
+- **Word 导出** — 集成 pandoc，一键生成 .docx 文件
+
+## 安装
+
+### 前置依赖
+
+- [Bun](https://bun.sh) ≥ 1.3
+- [pandoc](https://pandoc.org)（可选，需导出 Word 时安装）
+
+### 克隆并安装
+
+```bash
+git clone https://github.com/WXY-V1hZ/md2docx.git
+cd md2docx
+bun install
+```
+
+## 快速开始
+
+```bash
+# 处理 Markdown 并生成 Word 文档
+bun run src/index.ts docs/example.md
+
+# 只预处理，不调用 pandoc
+bun run src/index.ts docs/example.md --pandoc.enabled false
+
+# 指定输出路径
+bun run src/index.ts docs/example.md -o output/example.docx
+
+# 使用自定义配置文件
+bun run src/index.ts docs/example.md --config ./my-config.json
+```
+
+## 配置
+
+配置文件位于 `config/config.json`，通过 JSON Schema 提供 IDE 校验。
+
+所有配置项均可通过命令行覆盖：
+
+```bash
+bun run src/index.ts docs/example.md --figureCaption.enabled false
+```
+
+### 配置项概览
+
+| 配置项                      | 说明              | 默认值       |
+| --------------------------- | ----------------- | ------------ |
+| `detectTitle.enabled`       | 自定设置文档标题  | `true`       |
+| `detectTitle.strategy`      | 标题来源策略      | `"first-h1"` |
+| `normalizeHeadings.enabled` | 自动修正标题层级  | `true`       |
+| `numberHeadings.enabled`    | 自动为标题编号    | `true`       |
+| `figureCaption.enabled`     | 自动为图片编号    | `true`       |
+| `tableCaption.enabled`      | 自动为表格编号    | `true`       |
+| `renderMermaid.enabled`     | 渲染 Mermaid 图表 | `true`       |
+| `pandoc.enabled`            | 生成 Word 文档    | `true`       |
+
+## Web 配置编辑器
+
+```bash
+bun run src/web.ts
+```
+
+在浏览器中可视化编辑配置，实时校验并保存。
+
+## 处理流水线
+
+```
+Markdown
+    ↓
+解析 AST
+    ↓
+addTitle()        ← 提取文档标题
+    ↓
+normalizeHeadings() ← 修正标题层级
+    ↓
+numberHeadings()  ← 添加标题编号
+    ↓
+numberTables()    ← 添加表格编号
+    ↓
+renderMermaid()   ← Mermaid → PNG
+    ↓
+numberPictures()  ← 添加图片编号
+    ↓
+序列化 Markdown
+    ↓
+pandoc → DOCX
+```
+
+## 开发
+
+```bash
+# 测试
+bun test
+
+# 类型检查 + 代码检查 + 格式检查
+bun check
+```
+
+## 许可
+
+本项目基于 MIT 许可证开源 — 详见 [LICENSE](LICENSE)。

package/config/config.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "./config.schema.json",
+  "figureCaption": {
+    "enabled": true,
+    "format": "图 {n}",
+    "separator": "："
+  },
+  "tableCaption": {
+    "enabled": true,
+    "format": "表 {n}",
+    "separator": ""
+  },
+  "normalizeHeadings": {
+    "enabled": true
+  },
+  "numberHeadings": {
+    "enabled": true,
+    "detectExisting": true,
+    "useBuiltinRules": true
+  },
+  "renderMermaid": {
+    "enabled": true,
+    "theme": "tokyo-night-light",
+    "density": 200
+  },
+  "detectTitle": {
+    "enabled": true,
+    "strategy": "first-h1"
+  },
+  "pandoc": {
+    "enabled": true,
+    "outputName": "{file_name}.docx"
+  }
+}

package/config/config.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config.schema.json",
+  "title": "md2docx 配置",
+  "description": "md2docx 默认设置",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "figureCaption": {
+      "description": "图片编号",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动为图片编号",
+          "type": "boolean",
+          "default": true
+        },
+        "format": {
+          "description": "编号格式，{n} 代表序号",
+          "type": "string",
+          "default": "图 {n}"
+        },
+        "separator": {
+          "description": "编号与图片标题之间的分隔符",
+          "type": "string",
+          "default": "："
+        }
+      },
+      "required": ["enabled", "format", "separator"]
+    },
+    "tableCaption": {
+      "description": "表格编号",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动为表格编号",
+          "type": "boolean",
+          "default": true
+        },
+        "format": {
+          "description": "编号格式，{n} 代表序号",
+          "type": "string",
+          "default": "表 {n}"
+        },
+        "separator": {
+          "description": "编号与表格标题之间的分隔符",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": ["enabled", "format", "separator"]
+    },
+    "normalizeHeadings": {
+      "description": "标题层级",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动修正标题层级（标题编号开启时无法关闭）",
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": ["enabled"]
+    },
+    "numberHeadings": {
+      "description": "标题编号",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动为标题添加层级编号（同时修正标题层级）",
+          "type": "boolean",
+          "default": true
+        },
+        "detectExisting": {
+          "description": "重新编号前移除已有编号",
+          "type": "boolean",
+          "default": true
+        },
+        "existingPattern": {
+          "description": "识别已有编号的正则表达式（可选）",
+          "type": "string",
+          "default": ""
+        },
+        "useBuiltinRules": {
+          "description": "识别常见的中文和数字编号",
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": ["enabled", "detectExisting"]
+    },
+    "renderMermaid": {
+      "description": "Mermaid 图表",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "将 Mermaid 代码块转换为图片",
+          "type": "boolean",
+          "default": true
+        },
+        "theme": {
+          "description": "图表主题",
+          "type": "string",
+          "default": "tokyo-night-light"
+        },
+        "density": {
+          "description": "图片清晰度（DPI）",
+          "type": "integer",
+          "minimum": 72,
+          "default": 200
+        }
+      },
+      "required": ["enabled", "theme", "density"]
+    },
+    "pandoc": {
+      "description": "Word 导出",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "生成 Word 文档",
+          "type": "boolean",
+          "default": true
+        },
+        "outputName": {
+          "description": "输出文件名，{file_name} 代表源文件名",
+          "type": "string",
+          "default": "{file_name}.docx"
+        }
+      },
+      "required": ["enabled", "outputName"]
+    },
+    "detectTitle": {
+      "description": "文档标题",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "自动设置文档标题",
+          "type": "boolean",
+          "default": true
+        },
+        "strategy": {
+          "description": "标题来源",
+          "type": "string",
+          "enum": ["first-h1", "single-h1", "filename", "none"],
+          "enumDescriptions": {
+            "first-h1": "开头的一级标题",
+            "single-h1": "文档中唯一的一级标题",
+            "filename": "文件名",
+            "none": "不设置"
+          },
+          "default": "first-h1"
+        }
+      },
+      "required": ["enabled", "strategy"]
+    }
+  },
+  "required": [
+    "figureCaption",
+    "tableCaption",
+    "normalizeHeadings",
+    "numberHeadings",
+    "renderMermaid",
+    "detectTitle",
+    "pandoc"
+  ]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@v1hz/md2docx",
+  "version": "1.0.0",
+  "description": "基于 pandoc 的 Markdown 转 Word (docx) 工具，自动处理标题、编号、Mermaid 图表等",
+  "keywords": [
+    "converter",
+    "docx",
+    "markdown",
+    "mermaid",
+    "pandoc",
+    "word"
+  ],
+  "homepage": "https://github.com/WXY-V1hZ/md2docx#readme",
+  "bugs": {
+    "url": "https://github.com/WXY-V1hZ/md2docx/issues"
+  },
+  "license": "MIT",
+  "author": "WXY-V1hZ",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WXY-V1hZ/md2docx.git"
+  },
+  "bin": {
+    "md2docx": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "config/config.json",
+    "config/config.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "scripts": {
+    "cli": "bun run src/index.ts",
+    "test": "bun test",
+    "check": "bun tsc --noEmit && bun run oxlint && bun run oxfmt"
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.10",
+    "beautiful-mermaid": "^1.1.3",
+    "docx": "^9.7.1",
+    "pizzip": "^3.2.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "sharp": "^0.35.3",
+    "unified": "^11.0.5",
+    "xpath": "^0.0.34"
+  },
+  "devDependencies": {
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,200 @@
+import { type AppConfig } from "./config";
+
+type SchemaValueType = "boolean" | "integer" | "number" | "string";
+
+interface SchemaNode {
+  type?: SchemaValueType | "object";
+  description?: string;
+  default?: unknown;
+  enum?: unknown[];
+  minimum?: number;
+  properties?: Record<string, SchemaNode>;
+  required?: string[];
+}
+
+export interface ConfigOption {
+  path: string;
+  type: SchemaValueType;
+  description: string;
+  default?: unknown;
+  enum?: unknown[];
+  minimum?: number;
+  required: boolean;
+}
+
+export interface CliOptions {
+  help: boolean;
+  web: boolean;
+  mdPath?: string;
+  outputPath?: string;
+  configPath?: string;
+  overrides: Map<string, unknown>;
+}
+
+export function getConfigOptions(schema: SchemaNode): ConfigOption[] {
+  const options: ConfigOption[] = [];
+
+  function walk(node: SchemaNode, prefix: string): void {
+    if (node.type !== "object" || !node.properties) return;
+    for (const [name, child] of Object.entries(node.properties)) {
+      const path = prefix ? `${prefix}.${name}` : name;
+      if (child.type === "object") {
+        walk(child, path);
+      } else if (isValueType(child.type)) {
+        options.push({
+          path,
+          type: child.type,
+          description: child.description ?? "",
+          default: child.default,
+          enum: child.enum,
+          minimum: child.minimum,
+          required: node.required?.includes(name) ?? false,
+        });
+      }
+    }
+  }
+
+  walk(schema, "");
+  return options;
+}
+
+export function parseCliArgs(args: string[], configOptions: ConfigOption[]): CliOptions {
+  const optionsByName = new Map(configOptions.map((option) => [option.path, option]));
+  const result: CliOptions = { help: false, web: false, overrides: new Map() };
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "-h" || arg === "--help") {
+      result.help = true;
+      continue;
+    }
+    if (arg === "--web") {
+      result.web = true;
+      continue;
+    }
+    if (arg === "-o" || arg === "--config") {
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${arg} 缺少路径`);
+      }
+      if (arg === "-o") result.outputPath = value;
+      else result.configPath = value;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      const option = optionsByName.get(name);
+      if (!option) throw new Error(`未知参数：${arg}`);
+      const value = args[++i];
+      if (value === undefined) throw new Error(`${arg} 缺少值`);
+      result.overrides.set(name, parseConfigValue(value, option));
+      continue;
+    }
+    if (arg.startsWith("-") && !isNumericArgument(arg)) {
+      throw new Error(`未知参数：${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (!result.help && !result.web) {
+    if (positional.length === 0) throw new Error("缺少 Markdown 文件路径");
+    if (positional.length > 1) throw new Error("只能指定一个 Markdown 文件路径");
+    result.mdPath = positional[0];
+  }
+  return result;
+}
+
+export function applyConfigOverrides(
+  config: AppConfig,
+  overrides: Map<string, unknown>,
+): AppConfig {
+  const merged = structuredClone(config) as unknown as Record<string, unknown>;
+  for (const [path, value] of overrides) {
+    const segments = path.split(".");
+    let target = merged;
+    for (const segment of segments.slice(0, -1)) {
+      const next = target[segment];
+      if (!isRecord(next)) throw new Error(`配置路径不存在：${path}`);
+      target = next;
+    }
+    target[segments.at(-1)!] = value;
+  }
+  return merged as unknown as AppConfig;
+}
+
+export function formatHelp(configOptions: ConfigOption[]): string {
+  const lines = [
+    "用法:",
+    "  md2docx <md-path> [选项]",
+    "",
+    "选项:",
+    "  -o <path>                         输出 docx 路径",
+    "  --config <path>                   配置文件路径，默认 config/config.json",
+    "  --web                             打开默认配置的网页编辑器",
+    "  -h, --help                        显示帮助",
+    "",
+    "配置覆盖:",
+  ];
+
+  for (const option of configOptions) {
+    const constraints = [
+      option.default === undefined ? undefined : `默认: ${String(option.default)}`,
+      option.enum ? `可选: ${option.enum.join(" | ")}` : undefined,
+      option.minimum === undefined ? undefined : `最小: ${option.minimum}`,
+    ].filter(Boolean);
+    lines.push(`  --${option.path} <${option.type}>`);
+    lines.push(
+      `      ${option.description}${constraints.length ? `（${constraints.join("；")}）` : ""}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function parseConfigValue(value: string, option: ConfigOption): unknown {
+  let parsed: unknown;
+  switch (option.type) {
+    case "boolean":
+      if (value !== "true" && value !== "false") {
+        throw new Error(`--${option.path} 需要 boolean（true 或 false），收到：${value}`);
+      }
+      parsed = value === "true";
+      break;
+    case "integer":
+      if (!/^-?\d+$/.test(value)) {
+        throw new Error(`--${option.path} 需要整数，收到：${value}`);
+      }
+      parsed = Number(value);
+      break;
+    case "number":
+      parsed = Number(value);
+      if (!Number.isFinite(parsed)) {
+        throw new Error(`--${option.path} 需要数字，收到：${value}`);
+      }
+      break;
+    case "string":
+      parsed = value;
+      break;
+  }
+
+  if (option.enum && !option.enum.includes(parsed)) {
+    throw new Error(`--${option.path} 必须是以下值之一：${option.enum.join(", ")}`);
+  }
+  if (typeof parsed === "number" && option.minimum !== undefined && parsed < option.minimum) {
+    throw new Error(`--${option.path} 不能小于 ${option.minimum}`);
+  }
+  return parsed;
+}
+
+function isValueType(type: SchemaNode["type"]): type is SchemaValueType {
+  return type === "boolean" || type === "integer" || type === "number" || type === "string";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNumericArgument(value: string): boolean {
+  return /^-\d/.test(value);
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+export interface CaptionStyle {
+  enabled: boolean;
+  format: string;
+  separator: string;
+}
+
+export interface MermaidConfig {
+  enabled: boolean;
+  theme: string;
+  density: number;
+}
+
+export interface BooleanConfig {
+  enabled: boolean;
+}
+
+export interface HeadingNumberingConfig {
+  enabled: boolean;
+  detectExisting: boolean;
+  existingPattern?: string;
+  useBuiltinRules?: boolean;
+}
+
+export type TitleExtractStrategy = "first-h1" | "single-h1" | "filename" | "none";
+
+export interface TitleConfig {
+  enabled: boolean;
+  strategy: TitleExtractStrategy;
+}
+
+export interface PandocConfig {
+  enabled: boolean;
+  outputName: string;
+}
+
+export interface AppConfig {
+  figureCaption: CaptionStyle;
+  tableCaption: CaptionStyle;
+  normalizeHeadings: BooleanConfig;
+  numberHeadings: HeadingNumberingConfig;
+  renderMermaid: MermaidConfig;
+  detectTitle: TitleConfig;
+  pandoc: PandocConfig;
+}
+
+export async function loadConfig(path: string): Promise<AppConfig> {
+  const exists = await Bun.file(path).exists();
+  if (!exists) throw new Error(`找不到配置文件：${path}`);
+  const raw = JSON.parse(await Bun.file(path).text()) as Record<string, unknown>;
+  delete raw.$schema;
+  return raw as unknown as AppConfig;
+}