最近我把AI生成的Markdown内容整理成Word文档差点被公式和流程图逼疯。AI写作工具确实方便输出一段带LaTeX公式、Mermaid流程图、表格的技术说明文案质量没得说。但真要把这些内容交给导师、同事或者客户人家要的是docx不是.md文件。直接复制粘贴公式碎成纯文本流程图变成一行乱码表格线乱七八糟。后来我搭了一套基于Pandoc和Mermaid-CLI的转换方案才算把这个流程彻底理顺。这篇文章就把这套方案完整拆开讲从环境安装、Mermaid图渲染、Pandoc参数配置到各种翻车现场和解决方案全部记录下来。适合经常需要把AI生成内容转成正式文档的人也适合Obsidian、Typora用户想在本地一键导出Word的朋友。1. 为什么选PandocMermaid-CLI做Markdown到Word转换1.1 直接复制粘贴为什么不行很多人第一反应是AI生成的内容我直接全选复制粘到Word里不就行了如果是纯文本段落确实可以。但只要内容里出现下面三类元素复制粘贴就是灾难第一公式。AI输出的数学公式通常是LaTeX语法比如$\alpha \beta \gamma$。Word原生公式用的是OMML格式和LaTeX完全是两套体系。直接粘贴Word只会把$...$当普通字符处理结果是满屏的反斜杠和花括号。第二Mermaid图。AI生成的流程图、时序图、状态图在网页上能看到渲染好的图形但复制到Word里就只剩代码块文本。截图保存倒是能看但清晰度不稳定而且以后想改内容还得重新生成一遍。第三表格。AI为了方便经常输出Markdown管道表格。复制到Word后列宽、对齐、边框全是乱的双线变单线、文字不居中后期调整非常痛苦。所以我从一开始就没考虑“复制粘贴”这种野路子而是选择用命令行工具做真转换。1.2 Pandoc和Mermaid-CLI在这个方案里的分工这套方案的核心就两个工具Pandoc和Mermaid-CLI。Pandoc是文档转换界的瑞士军刀它能把Markdown、HTML、LaTeX、docx、PDF等几十种格式互相转换。最关键的是Pandoc能正确解析Markdown里的LaTeX数学语法并在生成docx时转成Word原生的OMML公式。也就是说转换后的公式在Word里是可以双击编辑的不是一张图片也不是纯文本。Mermaid-CLI也就是mmdc负责处理Mermaid图。它把Mermaid代码块拿去渲染生成高清PNG或SVG图片然后我再让Pandoc把这些图片嵌入到Word文档里。这样流程图就变成了真正的图片清晰度可控排版也不乱。简单说Pandoc管“文本和公式”Mermaid-CLI管“图形”两者配合才能完整覆盖AI生成Markdown的常见组成元素。1.3 这套方案还能用在哪些场景我最初是为了把AI写的内容转成Word交作业后来发现这套流程的应用场景比想象中广Obsidian或Typora用户笔记里记了大量Mermaid图和数学公式想发给不用Markdown的同事。用AI生成技术方案、需求文档、专利交底材料最终要提交Word版本。用Git管理文档的团队需要把.md文档批量导出成Word归档。写技术博客的人想快速把Markdown草稿转成Word再微调格式。只要你的Markdown里用到公式、流程图、表格这三类元素这套方案基本都能处理。2. 环境准备与工具安装2.1 Pandoc安装Pandoc的安装没有太多坑各个平台都有现成的方式Windows直接用winget install --id JohnMacFarlane.Pandoc或者去GitHub Releases页下载.msi安装包。macOSbrew install pandoc。LinuxDebian/Ubuntusudo apt install pandoc但apt源里的版本可能偏老建议去GitHub下载最新的deb包。安装完验证一下版本pandoc --version只要能看到版本号说明Pandoc已经就绪。我建议尽量用2.14以上版本对Markdown扩展语法和docx生成的兼容性更好。2.2 Node.js与Mermaid-CLI安装Mermaid-CLI是Node.js包所以要先装Node.js。建议装18以上的LTS版本太老的Node会导致依赖安装失败。装好Node之后全局安装mermaid-js/mermaid-clinpm install -g mermaid-js/mermaid-cli安装完成后验证mmdc --version注意mmdc第一次渲染Mermaid图时需要调用Chromium或Playwright来做渲染。如果本机没有现成的Chromium它会自动下载一个。这个过程比较吃网络如果下载失败可以多试几次或者设置环境变量PUPPETEER_SKIP_DOWNLOAD配合本机已有的Chrome路径来使用。具体怎么配后面常见问题部分会展开。2.3 制作一个reference.docx样式模板Pandoc生成Word时默认会使用一套内置样式。默认样式能用但出来的文档美观度一般表格、标题字体都不是很好看。我强烈建议先导出一份模板改好样式后再复用。生成模板的命令pandoc --print-default-data-file reference.docx custom-reference.docx然后用Word打开custom-reference.docx修改里面的“正文”“标题1”“标题2”“表格”等样式。比如把正文字体改成宋体五号、标题改成黑体、表格边框和对齐方式调好。保存后后续每次转换都用--reference-doccustom-reference.docx指定这个模板。这一步其实是整个方案里最能提升出片质量的关键。很多人在这一步偷懒结果生成的Word总是有一股“默认味”标题层级不明显表格边框乱七八糟。3. 转换器核心实现从Markdown到Word的完整流程3.1 整体转换链路简单来说整个转换分三步预处理扫描Markdown文件找出所有Mermaid代码块。渲染替换用mmdc把每个Mermaid代码块渲染成PNG图片并把原来的代码块替换成Markdown图片引用。正式转换用Pandoc把处理后的Markdown转成docx。为什么要先渲染图片再交给Pandoc因为Pandoc本身不认识Mermaid代码块它只会把mermaid当成一个普通代码块原样写进Word。如果我们提前把它替换成Pandoc就知道这是一张图片会自动嵌入并保持图片排版。3.2 mmdc渲染Mermaid图片的具体命令先看看单张图怎么渲染。假设有一个flow.mmd文件内容是一段Mermaid语法graph TD A[开始] -- B{是否完成} B -- 是 -- C[输出结果] B -- 否 -- D[继续处理]渲染成PNGmmdc -i flow.mmd -o flow.png -b white -s 3 -w 2048几个参数的意思-i指定输入文件。-o指定输出图片。-b white把背景设为白色。Mermaid默认渲染出的PNG背景是透明的透明背景在Word里显示时容易受主题影响变黑或变灰所以这里必须设成白色。-s 3是缩放比例。Mermaid渲染出来的矢量图默认尺寸偏小放到Word里会模糊。用3倍缩放Word里即便放大到页面宽度边缘依然清晰。-w 2048是最大宽度。这个参数配合缩放能保证最终图片够大。如果有多张图手动一张张执行肯定不行所以要写脚本。3.3 用Python脚本统一处理我这里写了一个Python脚本专门干“扫描Mermaid代码块→渲染图片→替换引用→调用Pandoc”这件事。脚本直接放在Markdown文件同目录下运行即可。import re import os import subprocess import tempfile import uuid def render_mermaid_blocks(md_content, md_dir, image_dirimages): # 匹配 mermaid 和 包裹的代码块 pattern re.compile(rmermaid\s*\n(.*?), re.S) image_abs_dir os.path.join(md_dir, image_dir) os.makedirs(image_abs_dir, exist_okTrue) def replace(match): mermaid_code match.group(1).strip() if not mermaid_code: return # 每个图片用唯一文件名避免相互覆盖 img_name fmermaid_{uuid.uuid4().hex[:8]}.png img_abs_path os.path.join(image_abs_dir, img_name) # 把Mermaid代码写入临时 .mmd 文件 with tempfile.NamedTemporaryFile(w, suffix.mmd, deleteFalse, encodingutf-8) as f: f.write(mermaid_code) temp_mmd_path f.name try: subprocess.run( [ mmdc, -i, temp_mmd_path, -o, img_abs_path, -b, white, -s, 3, -w, 2048, ], checkTrue, capture_outputTrue, ) except subprocess.CalledProcessError as e: print(Mermaid渲染失败请检查代码语法) print(mermaid_code) print(e.stderr.decode(utf-8, errorsignore)) return # 替换成相对路径Pandoc以 --resource-path 为基准找图片 return f new_content pattern.sub(replace, md_content) return new_content def convert_md_to_docx(md_path, reference_doccustom-reference.docx): md_dir os.path.dirname(os.path.abspath(md_path)) with open(md_path, r, encodingutf-8) as f: content f.read() content render_mermaid_blocks(content, md_dir) # 写出中间Markdown文件避免直接污染原文件 temp_md_path os.path.join(md_dir, _temp_converted.md) with open(temp_md_path, w, encodingutf-8) as f: f.write(content) docx_path os.path.splitext(md_path)[0] .docx cmd [ pandoc, temp_md_path, -o, docx_path, --resource-path., --from, markdowntex_math_dollarstex_math_single_backslashpipe_tables, --to, docx, ] if os.path.exists(reference_doc): cmd [--reference-doc, reference_doc] subprocess.run(cmd, checkTrue) print(f转换完成{docx_path}) if __name__ __main__: # 用法python convert_md_to_docx.py 你的文档.md import sys if len(sys.argv) 2: print(请在命令行指定Markdown路径) sys.exit(1) convert_md_to_docx(sys.argv[1])这个脚本有几个设计点值得说明用uuid生成图片文件名避免多个文档、多张图相互覆盖。渲染失败时不会整个脚本崩溃而是打印出Mermaid源码方便排查。中间文件_temp_converted.md保留了所有替换好的图片引用如果Pandoc那步出错可以直接用这个中间文件手动排查。命令参数里显式开启了tex_math_dollars和tex_math_single_backslash把AI生成时常见的$...$、$$...$$、\(...\)公式语法都覆盖到。3.4 Pandoc转换命令与关键参数脚本里已经封装了Pandoc命令单独拿出来看是这样pandoc _temp_converted.md -o output.docx \ --resource-path. \ --from markdowntex_math_dollarstex_math_single_backslashpipe_tables \ --to docx \ --reference-doccustom-reference.docx参数逐个解释--resource-path.告诉Pandoc去当前目录找图片资源。必须加这个否则脚本生成的images/xxx.png引用会让Pandoc找不到文件。--from markdowntex_math_dollarstex_math_single_backslashpipe_tables指定Markdown方言。重点在于公式扩展tex_math_dollars支持$...$和$$...$$tex_math_single_backslash支持\(...\)和\[...\]。很多AI模型喜欢输出\(...\)不加这个扩展就会漏解析。--reference-doccustom-reference.docx使用我们提前做好的模板。3.5 转换器工具使用效果说明这里补一张效果对比说明方便你直观感受转换前后的差异。内容类型AI生成的Markdown源内容转换后的Word效果行内公式质能方程 $Emc^2$质能方程 Emc²Word公式对象可编辑块级公式$$\int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2}$$独立公式行显示为Word原生公式Mermaid流程图mermaid graph TD A--B 高清PNG图片嵌入文档显示完整表格项目我用实际文档跑过几十次最终生成的Word里公式双击后能打开Word公式编辑器流程图直接是图片可以拖动缩放表格线也正常。整个效果基本达到“交上去不用大改”的状态。4. 公式、表格、图片在Word中的细节处理4.1 LaTeX数学公式如何变成Word原生公式Pandoc对公式的处理是整个方案里最让人省心的部分。AI生成的Markdown里公式语法基本是LaTeXPandoc解析后会在docx里自动写成OMML。OMML是Word的公式原生格式所以你双击公式看到的不是图片而是Word公式编辑器里可修改的结构。这里有个关键点AI生成内容时公式可能有三种写法。行内公式用一对美元符号$x^2 y^2 z^2$块级公式用两对美元符号$$\sum_{i1}^n i \frac{n(n1)}{2}$$有时候AI会用括号形式\(x1\)或\[...\]所以Pandoc的--from参数里一定要把两种公式扩展都打开否则会出现公式原样漏出变成纯文本。我在脚本里写的markdowntex_math_dollarstex_math_single_backslash就是同时兼容这两种写法。如果转换后某个复杂公式显示异常不要急着怀疑Pandoc先检查一下源Markdown里公式语法是否完整。比如大括号\frac后面有没有正确闭合这些AI偶尔会漏。4.2 Markdown表格转Word后的排版问题Markdown管道表格转成Word后Pandoc会把它变成一个真正的Word表格。但默认表格样式比较朴素边框和对齐方式都要靠reference.docx模板来控制。很多人遇到的问题——“表格双线变单线”“文字不居中”多半是模板样式没调好。解决办法打开custom-reference.docx。找到“Table”或“表格”样式。把边框设为需要的单线或三线表样式。把单元格对齐方式设为水平居中、垂直居中。保存后重新转换。如果不想动模板也可以在Word里全选表格手动调整边框和居中。但这样对大文档不友好还是模板一劳永逸。另外Markdown表格无法直接指定每个单元格的宽度。Pandoc会根据内容自动分配列宽。如果对列宽有严格要求建议转换后用Word的“布局→自动调整→根据窗口调整表格”功能统一处理或者直接用Pandoc的grid table语法在Markdown源码里用------的ASCII表格画法指定列宽。4.3 Mermaid图片的清晰度与Word排版Mermaid图片在Word里常见的问题有两个模糊和超宽。模糊的原因主要是渲染尺寸不够。我前面强调的-s 3就是解决这个问题的。缩放比例不够时可以继续调高比如-s 4。但注意缩放不是无限往上调图片文件会越来越大Word打开也会变慢。一般-s 3配合-w 2048已经能覆盖99%的场景。超宽的问题常常出现在流程图或甘特图分支较多的情况。图片宽度超过Word页面可排版宽度时会撑破页面。解决办法有两个方向渲染时把-w调小一点比如1280但是分支多了会缩小到看不清。转换后在Word里手动选中图片拖动角落缩放到合适大小。如果是批量文档可以在模板中为图片设置一个默认的“嵌入式”或“四周型”环绕方式减少后期调整成本。我个人的习惯是分支少用默认尺寸分支多就单独手动调一次毕竟AI生成的图很少需要反复调整。5. 常见问题与排查技巧实录5.1 Mermaid-CLI渲染类问题mmdc在运行中常见的报错主要集中在这几类问题现象可能原因解决办法Could not find Chromium本机没有配套的Chromium或者首次下载失败手动指定本机Chrome路径mmdc -p puppeteer-config.json配置文件里写executablePath: C:/Program Files/Google/Chrome/Application/chrome.exe渲染图片是空白Mermaid代码语法错误或者某些语法版本不支持先用Mermaid Live Editor在线验证代码升级mermaid-js/mermaid-cli到最新版渲染时中文显示为方块系统缺少中文字体安装中文字体并在Puppeteer配置里设置args: [--font-render-hintingnone]图片背景是黑色没有指定-b white渲染命令务必加上-b white5.2 Pandoc转换与Word显示问题Pandoc这边踩坑也很常见尤其是刚开始接触的时候。问题现象可能原因解决办法生成的Word打不开提示损坏Pandoc版本过旧或输入Markdown有异常字符升级Pandoc到最新版检查Markdown文件编码是否为UTF-8图片不显示只有裂图没有加--resource-path.或者图片引用路径不对确保脚本用相对路径生成图片引用Pandoc命令加--resource-path.公式显示成反斜杠文本--from参数没开tex_math_dollars或tex_math_single_backslash按前面的命令补全扩展中文全部乱码文件编码不是UTF-8或者Word打开时编码识别错误用UTF-8无BOM保存Markdown转换时Python里用encodingutf-8读取表格双线变单线、文字不居中reference.docx模板样式未调整修改模板里的Table样式边框、对齐设为需要的格式生成的Word非常大图片分辨率太高或数量太多适当降低-s和-w参数或改用JPG格式但透明背景会变白5.3 AI生成Markdown的兼容性处理AI生成内容有一个比较尴尬的问题不是每次输出的Markdown语法都规范。比如Mermaid代码块有时会写成mermaid后面多一个空格有时会带一个语言标记还有时Mermaid代码和之间有额外的空行。我的正则已经尽量做了兼容但如果你遇到某个代码块没有被替换可以先手动看一下源文件里实际语法是什么然后调整正则表达式。公式方面AI偶尔会把行内公式写成$ Emc^2 $数学模式里带了多余的空格。Pandoc遇到这种情况一般也能处理但某些复杂命令可能出错。稳妥的做法是转换前先人工扫一眼公式重点看有没有没闭合的$符号。5.4 常见问题速查表把上面这些归纳成一张速查表方便遇到问题时直接查。问题优先排查点Mermaid图不渲染mmdc是否安装、版本、Chromium是否存在Mermaid图渲染出来不对Mermaid语法本身是否有误、是否涉及新特性公式变成纯文本Pandoc的--from是否包含公式扩展图片不显示--resource-path是否正确、相对路径是否对中文乱码文件编码是否为UTF-8表格样式不对reference.docx模板中的表格样式生成的Word过大图片缩放比例和宽度6. 扩展思路与自动化建议这套方案搭好之后可以继续往两个方向扩展。第一个方向是接入Obsidian或Typora的工作流。Obsidian社区有obsidian-pandoc插件它本身就能调用Pandoc导出Word。如果我们把上面的预处理脚本做成一个外部脚本再通过Obsidian的自定义命令触发就能做到“在Obsidian里一键把当前笔记转成Word”。Typora的用户也可以把Pandoc配置为导出服务再配合预处理脚本使用。第二个方向是批量转换。如果你手头有一整个目录的Markdown文件可以在脚本外面套一层循环逐个调用convert_md_to_docx。这样整理历史笔记、批量生成报告初稿都很方便。还有个方向是嵌入到自动化工作流里比如用Coze这类工具搭建“AI生成Markdown→自动转Word”的流水线。思路是AI输出Markdown之后直接把内容传给一个执行脚本的节点脚本完成Mermaid渲染和Pandoc转换最终输出Word文件。这样人工只需要审阅最终结果。不过在自动化之前请务必保留一份原始Markdown。因为Word文件后续改格式很痛苦而Markdown改内容再重新转换非常快。我现在的习惯是源Markdown永远保留Word只是交付物。最后再分享一个小技巧我踩过几次坑之后固定下来的工作流是这样的AI生成的Markdown内容先保存为.md文件用脚本渲染Mermaid图并转成Word然后用WPS或者Word的“导航窗格”快速检查标题层级最后只针对个别图片和表格做微调。整个过程从拿到AI内容到交付Word十分钟以内能完成。如果你也经常被“AI写的Markdown怎么交Word”这个问题困扰建议直接照着这套流程搭一遍。第一次配置环境可能花个半小时但之后就真的是一劳永逸。公式能编辑、图片清晰、表格正常基本不需要返工。