Markdown 转 Word 交付指南：样式映射与行内降级

平台要 .docx、编辑部收 Word、甲方只认 OFFICE 格式——Markdown 草稿写到最后一公里卡在交付上。反向转换(Word 转 Markdown 的姊妹篇)是做迁移，这一篇是做交付：目标不是「转出来有内容」，而是收件人打开后能继续编辑、能用样式面板导航、能把文档接进他们自己的流程。

两条路线：pandoc 一条命令(本地批量)，或 Markdown 转 Word 工具 在浏览器里完成(粘贴、转换、下载，文件不出本机)。

「可编辑」比「看起来像」重要

劣质转换器的典型产物：标题是一行 22 号加粗宋体，看起来是标题，但样式面板里它是「正文」。后果立刻显现：

• 收件人打开导航窗格，目录是空的——Word 靠 Heading 样式生成导航树；
• 想改字号，得逐段手选，因为样式没挂上；
• 「自动生成目录」功能找不到任何标题。

合格转换的判据就一条：打开 Word 的样式面板，# 落在「标题 1」里。本文讨论的两条路线都满足，因为它们输出的都是 Word 原生样式，不是视觉模仿。

路线一:pandoc(适合批量交付)

pandoc draft.md -o deliverable.docx

进阶两个参数:--reference-doc=template.docx 用自己的模板(套公司的字体、页眉、封面样式);--toc 自动生成目录页。批量交付配合 shell 循环即可。pandoc 的 docx 输出质量是开源方案里最好的，重度交付场景首选。

路线二:浏览器本地转换(粘贴即走，零安装)

偶尔交付一篇、或者环境里装不了 pandoc(公司锁死的电脑、客户的机器)，浏览器路线更省事：

1. 打开 Markdown 转 Word 工具;
2. 粘贴 Markdown 源文;
3. 点转换 → 下载 .docx。

全部解析和打包在你浏览器进程里完成，断网可用。反向(拿到的 Word 要进 md 仓库)用 Word 转 Markdown 工具,同站本地完成。

样式映射对照

行内降级清单(用前必读)

浏览器版工具目前对这些 Markdown 行内语法降级为纯文本——不是 bug,是有意的取舍，但你得知道：

• **粗体**、*斜体*、`行内代码` → 转为普通文本(格式标记被剥掉，文字保留);
• 图片 ![]() 与链接 [text](url) → 保留文字，URL 与图像内容丢失；
• 嵌套列表 → 子项提升为同级。

所以它的定位是文字型交付：方案书、需求稿、周报、文章初稿。需要保真行内格式和图片的正式排版，走 pandoc 路线，或者转换后人工补一轮格式。判断规则很简单：文档里行内格式和图占比越高，越应该用 pandoc。

实现注记 / Implementer's note

浏览器版实现选择了 marked 的 lexer 直接产出 token 流、逐 token 映射到 docx 库对象的路径，而不是更常见的「marked 转 HTML → HTML 塞进 docx」两跳——中间少一层 HTML 语义近似，标题层级、表格结构、代码块边界都是 lexer 的一手信息。docx 库(Packer/Paragraph/Table)动态 import,粘贴前不加载。代码块的灰底纹用 shading 实现，字体钉死 Consolas 避免中文环境落到宋体。blockquote 有意做成「斜体+缩进」而不是套 Word 的「引用」样式：不同 Word 版本的引用样式视觉差异太大，视觉近似反而稳定。行内降级是当前架构的自然边界——inline 映射层只处理 plain text,做行内 run 拆分要重写整层，收益(粗体斜体)配不上风险，不如把边界标清楚留给 pandoc。creator 元数据写了 ToolVault,文档属性里查得到来源。

FAQ

收到的人说打开是乱码/打不开？

先确认扩展名是 .docx(OOXML)。Word 2007+/WPS/Office 365 全系支持；老古董 Word 2003 需要安装兼容包，这是所有现代转换器的共同边界。

怎么让转换结果套用公司的字体和页眉？

pandoc 路线用 --reference-doc=公司模板.docx,样式定义会被继承。浏览器路线输出的是 Word 默认样式，套模板这件事交给收件人在 Word 里一键更换样式集(设计 → 样式集)，这也是原生样式相对视觉模仿的又一个好处。

为什么不支持图片？

浏览器版聚焦纯文本交付，图片涉及二进制资源打包与体积权衡，交给 pandoc(自动抽取嵌入)更稳。需要图片的文档建议本地 pandoc 处理。

能自动生成目录吗？

文档用的是原生 Heading 样式，所以收件人可以在 Word 里「引用 → 目录 → 自动目录」一键生成，比转换器预先写死目录页更灵活(页码由收件人的排版决定)。

这篇交付指南整理自 ToolVault 工具匣的双向文档转换实现，降级清单就是代码里真实的边界。

补充注记

选 lexer 直映射而非 HTML 两跳，最初不是因为架构洁癖，而是实测发现 HTML 中转会把 1. 开头的段落误判成列表(ordered-list 边界歧义)，token 流则保留「这就是个 paragraph」的一手判断——少一层表示，少一类歧义。