@v1hz/md2docx 1.0.5 → 1.2.0

package/README.md

@@ -1,62 +1,67 @@
-# md2docx
+<p align="center">
+  <img src="assets/logo.svg" alt="md2docx" width="160" height="160">
+</p>
 
-基于 pandoc 的 Markdown 转 Word (.docx) 工具，在转换前执行 AST 变换以提升文档输出质量。
+<h1 align="center">md2docx</h1>
 
-## 功能
+<p align="center">
+  基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。
+</p>
 
-将 Markdown 转换为格式精美的 Word 文档，自动处理：
+<p align="center">
+  <a href="https://www.npmjs.com/package/@v1hz/md2docx"><img src="https://img.shields.io/npm/v/@v1hz/md2docx" alt="npm version"></a>
+  <a href="https://github.com/WXY-V1hZ/md2docx"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
+</p>
 
-- **文档标题** — 从 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 时安装）
+将 Markdown 转换为格式精美的 Word 文档，自动处理：
 
-### 通过 npx（推荐，无需安装）
+| 功能               | 说明                                                       |
+| ------------------ | ---------------------------------------------------------- |
+| **文档标题**       | 从 frontmatter、H1 或文件名自动提取                        |
+| **标题层级归一化** | 修正标题层级跳跃，确保从 H1 开始连续递增                   |
+| **标题编号**       | 为标题添加多级编号（1、1.1、1.1.1 …），支持剥离已有编号    |
+| **表格编号**       | 自动为表格添加编号（表 1、表 2 …）                         |
+| **图片编号**       | 为独立图片添加编号（图 1、图 2 …）                         |
+| **Mermaid 图表**   | 将 Mermaid 代码块渲染为 PNG 图片                           |
+| **Word 导出**      | 集成 pandoc，传入自定义样式模板，一键生成 .docx            |
+| **样式定制**       | 通过 `style/style.json` 定义文档样式，支持从模板 docx 提取 |
+| **web 配置编辑器** | 浏览器中可视化编辑配置                                     |
 
-```bash
-npx @v1hz/md2docx README.md
-```
+## 安装
 
-### 全局安装
+_前置依赖_：[Bun](https://bun.sh) | [Pandoc](https://pandoc.org)
 
 ```bash
 npm install -g @v1hz/md2docx
-md2docx README.md
+md2docx docs/example.md
 ```
 
-### 从源码运行
-
-```bash
-git clone https://github.com/WXY-V1hZ/md2docx.git
-cd md2docx
-bun install
-bun run src/index.ts docs/example.md
-```
+也可通过 `npx @v1hz/md2docx` 直接运行。
 
 ## 快速开始
 
 ```bash
 # 处理 Markdown 并生成 Word 文档
-npx @v1hz/md2docx docs/example.md
+md2docx docs/example.md
 
 # 只预处理，不调用 pandoc
-npx @v1hz/md2docx docs/example.md --pandoc.enabled false
+md2docx docs/example.md --pandoc.enabled false
 
 # 指定输出路径
-npx @v1hz/md2docx docs/example.md -o output/example.docx
+md2docx docs/example.md -o output/example.docx
+
+# 打开 web 网页自定义配置
+md2docx --web
 
 # 使用自定义配置文件
-npx @v1hz/md2docx docs/example.md --config ./my-config.json
+md2docx docs/example.md --config ./my-config.json
+
+# 清除缓存（预处理中间产物、样式模板等）
+md2docx clean
 ```
 
 ## 配置
@@ -66,62 +71,104 @@ npx @v1hz/md2docx docs/example.md --config ./my-config.json
 所有配置项均可通过命令行覆盖：
 
 ```bash
-npx @v1hz/md2docx docs/example.md --figureCaption.enabled false
+md2docx 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 配置编辑器
+| 配置项                           | 说明                                                         | 默认值                |
+| -------------------------------- | ------------------------------------------------------------ | --------------------- |
+| `detectTitle.enabled`            | 自动设置文档标题                                             | `true`                |
+| `detectTitle.strategy`           | 标题来源策略：`first-h1` / `single-h1` / `filename` / `none` | `"first-h1"`          |
+| `normalizeHeadings.enabled`      | 自动修正标题层级                                             | `true`                |
+| `numberHeadings.enabled`         | 自动为标题编号（开启时自动启用 normalizeHeadings）           | `true`                |
+| `numberHeadings.detectExisting`  | 重新编号前移除已有编号                                       | `true`                |
+| `numberHeadings.useBuiltinRules` | 识别常见的中文和数字编号                                     | `true`                |
+| `figureCaption.enabled`          | 自动为图片编号（格式：`图 {n}`）                             | `true`                |
+| `figureCaption.format`           | 图片编号格式                                                 | `"图 {n}"`            |
+| `figureCaption.separator`        | 编号与标题之间的分隔符                                       | `"："`                |
+| `tableCaption.enabled`           | 自动为表格编号（格式：`表 {n}`）                             | `true`                |
+| `tableCaption.format`            | 表格编号格式                                                 | `"表 {n}"`            |
+| `tableCaption.separator`         | 编号与标题之间的分隔符                                       | `" "`                 |
+| `renderMermaid.enabled`          | 渲染 Mermaid 图表为 PNG                                      | `true`                |
+| `renderMermaid.theme`            | 图表主题                                                     | `"tokyo-night-light"` |
+| `renderMermaid.density`          | 图片清晰度（DPI，最小 72）                                   | `200`                 |
+| `pandoc.enabled`                 | 生成 Word 文档                                               | `true`                |
+| `pandoc.outputName`              | 输出文件名，`{file_name}` 代表源文件名                       | `"{file_name}.docx"`  |
+
+## 样式定制
+
+`style/style.json` 定义了 docx 输出的全部样式，包括字体、字号、颜色、缩进、间距等。
+
+### 从模板 docx 提取样式
+
+如果你有一个排版精美的 docx 模板，可以提取其样式：
 
 ```bash
-bun run src/web.ts
+bun run src/style/extract.ts
 ```
 
-在浏览器中可视化编辑配置，实时校验并保存。
+提取后修改 `style/style.json`，转换时会自动使用这些样式生成输出文档。
+
+### 手动维护样式
+
+也可直接编辑 `style/style.json`。支持以下样式配置：
+
+- **文档默认样式**（`default.document`）：全局字体、字号、段落间距
+- **内置样式覆盖**（`default.heading1` … `default.heading6`、`default.title` 等）
+- **自定义段落样式**（`paragraphStyles`）
+- **自定义字符样式**（`characterStyles`）
+
+详细的样式字段定义参考 [docx 包文档](https://docx.js.org)。
 
 ## 处理流水线
 
+项目遵循单向处理流水线，每个步骤职责单一。
+
 ```
 Markdown
     ↓
 解析 AST
     ↓
-addTitle()        ← 提取文档标题
+addTitle()            ← 提取文档标题
     ↓
-normalizeHeadings() ← 修正标题层级
+normalizeHeadings()   ← 修正标题层级（最小深度 → H1，消除跳跃）
     ↓
-numberHeadings()  ← 添加标题编号
+numberHeadings()      ← 添加标题编号（1 / 1.1 / 1.1.1 …）
     ↓
-numberTables()    ← 添加表格编号
+numberTables()         ← 添加表格编号（表 1、表 2 …）
     ↓
-renderMermaid()   ← Mermaid → PNG
+renderMermaid()       ← Mermaid 代码块 → PNG 图片
     ↓
-numberPictures()  ← 添加图片编号
+numberPictures()      ← 添加图片编号（图 1、图 2 …）
     ↓
 序列化 Markdown
     ↓
-pandoc → DOCX
+生成样式模板 docx     ← 根据 style/style.json 生成 pandoc reference-doc
+    ↓
+pandoc → DOCX         ← 以 --reference-doc 传入样式模板
 ```
 
 ## 开发
 
+### 从源码运行
+
+```bash
+git clone https://github.com/WXY-V1hZ/md2docx.git
+cd md2docx
+bun install
+bun run src/index.ts docs/example.md
+```
+
+### 命令
+
 ```bash
 # 测试
 bun test
 
 # 类型检查 + 代码检查 + 格式检查
 bun check
+
+# 清除缓存
+bun run src/index.ts clean
 ```
 
 ## 许可

package/config/config.json

@@ -8,7 +8,7 @@
   "tableCaption": {
     "enabled": true,
     "format": "表 {n}",
-    "separator": ""
+    "separator": " "
   },
   "normalizeHeadings": {
     "enabled": true

package/config/config.schema.json

@@ -47,7 +47,7 @@
         "separator": {
           "description": "编号与表格标题之间的分隔符",
           "type": "string",
-          "default": ""
+          "default": " "
         }
       },
       "required": ["enabled", "format", "separator"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@v1hz/md2docx",
-  "version": "1.0.5",
-  "description": "基于 pandoc 的 Markdown 转 Word (docx) 工具，自动处理标题、编号、Mermaid 图表等",
+  "version": "1.2.0",
+  "description": "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
   "keywords": [
     "converter",
     "docx",

package/src/cli.ts

@@ -132,6 +132,7 @@ export function formatHelp(configOptions: ConfigOption[]): string {
   const lines = [
     "用法:",
     "  md2docx <md-path> [选项]",
+    "  md2docx clean",
     "",
     "选项:",
     "  -o <path>                         输出 docx 路径",
@@ -140,6 +141,9 @@ export function formatHelp(configOptions: ConfigOption[]): string {
     "  -v, --version                     显示版本号",
     "  -h, --help                        显示帮助",
     "",
+    "子命令:",
+    "  clean                             清除 tmp/ 缓存",
+    "",
     "配置覆盖:",
   ];
 

package/src/index.ts

@@ -1,17 +1,41 @@
 #!/usr/bin/env bun
 
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
 import { dirname, parse, resolve } from "path";
 import { $ } from "bun";
 
 import { applyConfigOverrides, formatHelp, getConfigOptions, parseCliArgs } from "./cli";
 import { loadConfig } from "./config";
-import { CONFIG_PATH, CONFIG_SCHEMA_PATH, PKG_DIR, formattedMdPath, preprocessDir } from "./paths";
+import {
+  CONFIG_PATH,
+  CONFIG_SCHEMA_PATH,
+  PKG_DIR,
+  TMP_DIR,
+  formattedMdPath,
+  preprocessDir,
+} from "./paths";
 import { preprocess } from "./preprocess/index";
 import { startWebEditor } from "./web";
+import { ensureTemplateDocx } from "./style/generate";
+
+async function cleanCache(): Promise<number> {
+  const resolved = resolve(TMP_DIR);
+  if (existsSync(resolved)) {
+    rmSync(resolved, { recursive: true, force: true });
+    console.log(`已清除缓存：${resolved}`);
+  } else {
+    console.log("缓存目录不存在，无需清理。");
+  }
+  return 0;
+}
 
 export async function run(args: string[]): Promise<number> {
   try {
+    // 检查子命令
+    const subcommand = args[0];
+    if (subcommand === "clean") {
+      return await cleanCache();
+    }
     const schema = JSON.parse(await Bun.file(CONFIG_SCHEMA_PATH).text());
     const configOptions = getConfigOptions(schema);
     const cli = parseCliArgs(args, configOptions);
@@ -46,10 +70,12 @@ export async function run(args: string[]): Promise<number> {
     writeFileSync(mdOutput, formattedMd, "utf-8");
 
     if (cfg.pandoc.enabled) {
+      const templatePath = await ensureTemplateDocx();
       const configuredName = cfg.pandoc.outputName.replaceAll("{file_name}", baseName);
       const docxOutput = resolve(cli.outputPath ?? configuredName);
       mkdirSync(dirname(docxOutput), { recursive: true });
-      const result = await $`pandoc ${mdOutput} -o ${docxOutput}`.nothrow();
+      const result =
+        await $`pandoc ${mdOutput} -o ${docxOutput} --reference-doc=${templatePath}`.nothrow();
       if (result.exitCode !== 0) {
         console.error(`pandoc 转换失败 (exit code ${result.exitCode}):`, result.stderr.toString());
         return 1;

package/src/paths.ts

@@ -27,11 +27,8 @@ export function formattedMdPath(baseName: string): string {
 /** 样式模块目录 */
 export const STYLE_DIR = `${TMP_DIR}/style`;
 
-/** 参考 docx 文件路径（样式提取的输入） */
-export const STYLE_REF_DOCX = `${STYLE_DIR}/ref.docx`;
-
-/** 样式 JSON 文件路径（提取结果的输出 / 模板生成的输入） */
-export const STYLE_JSON = `${STYLE_DIR}/style.json`;
+/** 样式配置文件（相对于包安装目录），用户维护的样式定义 */
+export const STYLE_CONFIG = resolve(PKG_DIR, "config/style.json");
 
 /** 生成的模板 docx 文件路径 */
-export const STYLE_TEMPLATE_DOCX = `${STYLE_DIR}/template.docx`;
+export const STYLE_TEMPLATE_DOCX = `${STYLE_DIR}/style.docx`;

package/src/style/extract.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { DOMParser } from "@xmldom/xmldom";
 import { useNamespaces } from "xpath";
 import PizZip from "pizzip";
@@ -372,10 +372,3 @@ export function extractStylesFromDocx(docxPath: string): ExtractedStyles {
 
   return result;
 }
-
-if (import.meta.main) {
-  const { STYLE_REF_DOCX, STYLE_JSON } = await import("../paths");
-  const styles = extractStylesFromDocx(STYLE_REF_DOCX);
-  writeFileSync(STYLE_JSON, JSON.stringify(styles, null, 2), "utf-8");
-  console.log(`Styles extracted from ${STYLE_REF_DOCX} to ${STYLE_JSON}`);
-}

package/src/style/generate.ts

@@ -0,0 +1,31 @@
+import { readFileSync, mkdirSync } from "fs";
+import { Document, Packer } from "docx";
+import { dirname } from "path";
+import { STYLE_CONFIG, STYLE_TEMPLATE_DOCX } from "../paths";
+
+export async function generateTemplateDocx(): Promise<void> {
+  const styles = JSON.parse(readFileSync(STYLE_CONFIG, "utf-8"));
+  const doc = new Document({
+    styles: styles,
+    sections: [],
+  });
+  const buf = await Packer.toBuffer(doc);
+  mkdirSync(dirname(STYLE_TEMPLATE_DOCX), { recursive: true });
+  await Bun.write(STYLE_TEMPLATE_DOCX, buf);
+}
+
+let _generatePromise: Promise<void> | null = null;
+
+export async function ensureTemplateDocx(): Promise<string> {
+  const exists = await Bun.file(STYLE_TEMPLATE_DOCX).exists();
+  if (!exists) {
+    if (_generatePromise === null) {
+      _generatePromise = generateTemplateDocx().catch((e) => {
+        _generatePromise = null; // 重置，允许下次重试
+        throw e;
+      });
+    }
+    await _generatePromise;
+  }
+  return STYLE_TEMPLATE_DOCX;
+}