md-to-docx

md-to-docx

使用此技能可可靠地将 Markdown 转换为 .docx 输出。

工作流

1. 确定执行模式：
   • 文件到文件转换使用 CLI 模式。
   • 应用代码集成使用编程模式。
2. 确认输入来源（Markdown 文件或 Markdown 字符串）。
3. 确认输出目标（.docx 文件路径或浏览器下载）。
4. 仅在需要时应用选项（对齐方式、字号、方向、字体系列、替换、模板、分节、页码）。
5. 运行转换，并报告生成的输出路径或文件名。

CLI 模式

使用以下命令：

npx @mohtasham/md-to-docx input.md output.docx
md-to-docx input.md output.docx
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
md-to-docx --help

CLI 约定：

• 必需的位置参数：<input.md> <output.docx>
• 可选的选项文件：--options <options.json> 或 -o <options.json>
• Options JSON 可包含与 API 相同的结构：style、template、sections 和 textReplacements
• 帮助标志：-h 或 --help
• 成功时，预期输出：DOCX created at: <absolute-path>
• 参考 DOCX 模式需要二进制输入，属于编程 API，而非 CLI 标志。

编程模式

import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const markdown = "# Title\n\nHello **DOCX**.";
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Trebuchet MS",
    heading1Alignment: "CENTER",
    paragraphAlignment: "JUSTIFIED",
    codeBlockAlignment: "LEFT",
    direction: "LTR"
  }
});

downloadDocx(blob, "output.docx");

使用 convertMarkdownToDocx(markdown, options?) 生成 DOCX Blob。 仅在浏览器环境中使用 downloadDocx(blob, filename?)。

参考 DOCX 工作流

明确选择以下一种：

• convertMarkdownWithReferenceDocxToBuffer(markdown, referenceBytes, options?) 会创建由 Markdown 控制的新正文，并采用参考文档中的命名样式、主题／字体、末节页面布局和页眉／页脚。
• patchMarkdownInDocxToBuffer(referenceBytes, patches, options?) 会保留现有正文，并替换 {{body}} 等命名占位符。

参考样式生成不会复制参考文档正文中的静态文本。样式名称重复时，优先使用精确的 { id: "..." } 选择器；如需使用 Word 中显示的名称，则使用 { name: "..." }。将上传的参考文档视为不可信内容，并保持默认 ZIP 限制，除非调用方有充分理由需要更大的上限。

多节文档

使用 options.template 设置共享默认值，使用 options.sections 设置各节的 Markdown 内容和覆盖选项：

const blob = await convertMarkdownToDocx("", {
  template: {
    footers: {
      default: { pageNumberDisplay: "currentAndTotal", alignment: "CENTER" }
    }
  },
  sections: [
    {
      markdown: "# Cover Page\n\nIntroduction here.",
      titlePage: true,
      headers: { first: { text: "Confidential", alignment: "RIGHT" } },
      pageNumbering: { start: 1, display: "none" }
    },
    {
      markdown: "# Chapter 1\n\nBody content.",
      style: { paragraphAlignment: "JUSTIFIED" },
      pageNumbering: { start: 1, display: "currentAndTotal" }
    }
  ]
});

每节可覆盖：style、headers、footers、pageNumbering、page（页边距／大小／方向）、titlePage 和 type（分节符类型）。

合并优先级：

• 首先应用全局 style
• template 提供共享的分节默认值
• 最后以各节选项为准

常见页脚页码模式可通过 pageNumbering.display 设置：none、current、currentAndTotal 或 currentAndSectionTotal。

图和表的引用

在独立图片或表格后放置 Pandoc 风格的题注段落，并在内容块与题注之间空一行。在正文中使用 [@fig:id] 或 [@tbl:id]：

See [@fig:flow] and [@tbl:metrics].

![Accessible flow diagram](flow.png)

: Request *flow* {#fig:flow}

| Metric | Value |
| --- | --- |
| p95 | 120 ms |

: Performance metrics {#tbl:metrics}

图和表的编号会跨节连续递增。使用 options.captions 设置标签、位置、对齐方式、斜体、字号和 failureMode。参考 DOCX 补丁模式不支持此语法，并会返回验证错误。

文本替换

使用 textReplacements 在转换前重写文本：

const blob = await convertMarkdownToDocx("# Hello oldText", {
  textReplacements: [
    { find: /oldText/g, replace: "newText" },
    { find: "Hello", replace: "Hi" }
  ]
});

Markdown 功能支持

支持的功能包括：

• 标题 # 至 #####
• 有序／无序列表
• 粗体、斜体、下划线（++text++）、删除线（~~text~~）
• 通过 fontFamily 样式选项自定义字体系列
• 引用块
• 表格（单元格内支持粗体、斜体、代码、链接和删除线等行内格式）
• 代码块和行内代码（可配置 codeBlockAlignment）
• 链接和图片
• 自动编号的图表题注和可点击的交叉引用
• 通过 textReplacements 在渲染前替换文本
• COMMENT: ...
• 单独成行的 [TOC]
• 单独成行的 \pagebreak
• Markdown 分隔线（---、***、___）会渲染为 Word 原生段落边框

样式选项速查

选项	值	默认值
paragraphAlignment	LEFT、CENTER、RIGHT、JUSTIFIED	LEFT
headingAlignment	同上	LEFT
heading1Alignment–heading5Alignment	同上	LEFT
blockquoteAlignment	同上	LEFT
codeBlockAlignment	同上	LEFT
fontFamily	任意字体名称字符串	Calibri
direction	LTR、RTL	LTR
tableLayout	autofit、fixed	autofit
tocFontSize	数字	库默认值

故障排除

• 如果 CLI 因参数错误而失败，请重新确认提供的恰好是两个位置路径。
• 如果选项解析失败，请检查 JSON 语法，并确保根节点是一个对象。
• 如果没有生成输出，请检查目标目录权限和路径拼写。
• 如果在 Node 中需要文件，请将返回的 Blob 字节写入磁盘，而不是使用 downloadDocx。
• 如果各节的编号结果异常，请确保每节都设置 pageNumbering.start 以重置计数。
• 如果首页页眉或页脚未显示，请在该节设置 titlePage: true。