如何使用Pandoc将docx文件转换为适配Azure Wiki的格式

适配Azure DevOps Wiki的Word转换方案 #

Azure DevOps Wiki使用基于GFM的自定义扩展语法，直接使用通用markdown转换参数无法匹配它的渲染规则，可按以下步骤调整：

1. 调整Pandoc转换参数

你之前尝试的通用格式参数都没有针对Azure Wiki的特性做适配，推荐使用以下命令转换：

pandoc -s "输入文件.docx" -t gfm --atx-headers --extract-media=./media --wrap=none --columns=999 --ascii -o "输出文件.md"

参数说明：

• -t gfm 以GFM为基础格式，匹配Azure Wiki的核心语法规则
• --atx-headers 强制生成#格式的标题，避免Pandoc默认生成的下划线式标题在Azure Wiki中渲染层级错乱
• --extract-media=./media 自动提取Word文档中的所有图片、内嵌素材到同级media文件夹，后续直接把media文件夹和md文件一起上传到Wiki仓库即可，路径自动匹配
• --wrap=none、--columns=999 取消Pandoc的自动换行截断，避免段落、表格被强行拆行导致格式混乱
• --ascii 转换特殊字符为ASCII编码，避免中文、特殊符号出现乱码

如果文档包含公式，额外添加--mathml参数，Azure Wiki原生支持MathML格式公式渲染，清晰度远高于转图片的效果。

2. 转换后微调优化

部分Word中的复杂格式无法通过工具1:1自动转换，可手动做少量调整：

• 合并单元格的复杂表格：Pandoc默认转出来的是拆分后的普通表格，可按照Azure Wiki的表格合并语法手动调整标记即可
• 自动编号标题：Word导出的自动编号可能会残留多余符号，手动删除后按Wiki的层级需求调整#的数量即可
• 列表缩进：统一调整列表缩进为2个空格，匹配Azure Wiki的列表渲染规则

3. 上传验证

把生成的md文件和media文件夹一起提交到Azure DevOps对应的Wiki代码仓库，即可正常渲染，效果基本可以对齐原Word文档的排版。

内容的提问来源于stack exchange，提问作者BFilip