用Python实现Word转Markdown:从python-docx到样式映射的完整实践
1. 先想明白:把 Word 搬进 Markdown,搬的到底是什么
1.1 转换的本质是“视觉格式”到“语义结构”的翻译
先说一个最容易让人产生误解的地方。很多人以为 DOCX 转 Markdown 就是把 Word 里的文本“提取”出来,再套上几个 # 号。我一开始也这么想,直到遇到第一份带三级目录的文档,才意识到问题没那么简单。
Word 里的标题,在视觉上可能是“黑体加粗、字号 16、段前段后间距 18 磅、自动编号”,而 Markdown 里的标题只是 # 到 ###### 六个层级。把一个视觉样式翻译成语义标记,需要搞清楚“这个段落为什么被设计成这种样子”,而不是“它看起来是什么样子”。换句话说,转换的过程是一次从视觉语言到结构语言的翻译,翻译的质量取决于你对 Word 文档内在结构的理解程度。
python-docx 读取段落文本只需要一行代码,但要把段落正确地写成 ## 二级标题,你得先判断它的 paragraph.style.name 是不是 Heading 2,或者它的样式层级到底继承自哪套模板。很多从 WPS 转存过来的文档,样式名是一堆乱码或者中文自定义名,靠默认映射根本猜不出来。
1.2 不同使用场景对转换质量的要求天差地别
随着深入,我逐渐发现“DOCX 转 Markdown”这个需求在不同的工作流里,对质量的宽容度完全不一样。我把它大致分成四类:
- 博客搬家:往往只要求正文、标题、代码块、图片能完整搬过去,表格丢了都能忍,反正博客排版还会再调。
- 知识库入库:要求就高很多。标题层级必须准确,否则检索系统拿到的文档结构与目录树是错位的;列表要能正确嵌套,否则片段切分后语义混乱。
- Git 版本管理:最关心的是“可读性”,同一份文档每次改动之后,Git 的 diff 要足够小、足够清晰,这就要求转换结果稳定、确定,不能每次跑出来都不一样。
- RAG 语料预处理:需要尽量保留表格、列表、层级关系,因为这些都是后续分块和向量化的锚点;图片大部分场景可以丢弃。
我这次的实际场景属于知识库入库加 Git 版本管理,要求恰好处于“不能太糊弄”的档次。如果你的场景只是临时转一篇博客,完全可以只上现成工具,没必要折腾自己写的转换器。
1.3 动手前的预期管理:哪些必须保,哪些可以扔
凡是做过一轮真实文档转换的人,都会得出同一个结论:DOCX 到 Markdown 是一个有损转换,别指望 100% 还原。关键是你自己心里要有一份“保留清单”和“放弃清单”。
我给自己定的保留清单是:标题层级、列表层级、加粗斜体、代码块、表格内容、图片文件、超链接地址。放弃清单是:字间距和行间距、页面边距与分页符、页眉页脚、水印、批注和修订痕迹。Word 里那些为了“好看”而存在的布局信息,转换到 Markdown 之后会变成一堆无意义的空行或换行,反而干扰阅读。我在批量处理前先把这份清单跟需求方对了一下,后面所有代码都是按这份清单来取舍的。这一步看着不起眼,实际上能省掉后期大量“这个怎么没转出来”的扯皮。
2. 现成工具实测:pandoc、mammoth、markitdown 谁更适合中文文档
2.1 三种方案的定位:通用转换器、专业转换器、多格式中转站
在我自己写代码之前,先把市面上的现成方案都跑了一遍。这里主要说三个:pandoc、mammoth,以及微软开源的 markitdown。这三个的定位其实差异很大。
pandoc 是文档转换界的瑞士军刀,支持格式多到数不清,DOCX 转 Markdown 只是它的日常功能之一。它转换时非常讲究“排版完整性”,会尽量保留 Word 里的章节顺序、列表、引用块等结构,但要注意它默认输出的 Markdown 带了很多 pandoc 自己的扩展语法,比如隐式标题层级转换和各类 div 标记,这些在你自己的知识库系统里未必兼容。
mammoth 是专门为了“把 DOCX 转成干净的 HTML 或 Markdown”而生的 Python 库。它的理念是:文档的视觉效果不重要,语义结构才重要。所以它默认就会把 Word 里的标题、粗体、列表等语义元素提取出来,丢掉大部分页面布局信息,输出非常干净。对于绝大多数普通文档,mammoth 转换出来的 Markdown 比 pandoc 更接近我想要的“人类可读”状态。
markitdown 是微软最近开源的多格式转换工具,定位更广:PDF、Word、Excel、PPT、图片都能转 Markdown,设计思路是给 AI 应用统一喂语料。它的 DOCX 转换内部也是走语义提取路线,但项目相对年轻,输出稳定性和对中文的支持还在迭代中。
2.2 实测输出:同样的 docx,三个工具给的结果长什么样
我拿同一份带有一级二级标题、一段加粗文字、一个无序列表、一张表格、一张图片的中文 docx 分别跑了一遍,简单记录一下体感:
| 工具 | 标题解析 | 列表解析 | 表格解析 | 图片处理 | 输出风格 |
|---|---|---|---|---|---|
| pandoc | 准确,但默认输出带扩展语法 | 支持嵌套列表 | 基本准确,合并单元格会折叠 | 导出到 media 目录,路径可用 | 排版信息保留多,偏重“还原” |
| mammoth | 准确,输出干净的 # | 支持嵌套列表 | 合并单元格会有重复 | 自动提取图片到指定目录 | 干净,偏重“语义” |
| markitdown | 准确,但样式命名简单粗暴 | 常见列表没问题 | 简单表格可以,复杂表格易乱 | 提取图片,路径可配置 | 面向语料,极简 |
需要说明的是,这只是我抽取的一批样本的体感,不是严谨的基准测试。三个工具对“用原生 Word 列表样式”的文档表现都很好,真正拉开差距的是那些“手打编号、手打空格对齐”的野路子文档。我遇到的一份文档里,所有列表项都是普通正文样式,只是人工在行首敲了“1.”和 Tab 键。pandoc 和 mammoth 把它们全部当成普通段落,markitdown 靠启发式勉强识别了一部分,但还是会把“1.11 子节”和“1.9 子节”的顺序弄错。这种情况你就是把整套工具链换一遍也解决不了,因为它们不可能比你更懂你公司文档的历史习惯。
2.3 什么时候可以停用轮子,什么时候必须自己写
那到底要不要自己写?我给自己定了几条判断标准,也分享给你参考。
如果你的文档来源单一、样式规范、不使用复杂的表格合并和图片排版,直接用 mammoth 就够了,代码量不超过二十行,转换结果稳定可靠。
如果文档来源乱七八糟,样式像是几代人接力维护的,但你对输出质量要求不高(比如只是备份归档),也可以继续用现成工具,接受部分内容错乱。
如果出现下面三种情况,就别继续修轮子了,直接考虑自己写:一是你需要批量控制转换细节,比如图片统一放到某个目录、代码块要按固定规则保留、列表要自动补齐层级;二是文档里有大量自定义样式名,比如“项目符号一级”“正文缩进加粗”,工具自带映射表完全猜不出你的业务含义;三是你需要把转换逻辑嵌入到定时任务里,且要求失败率和异常可控。我这次就是第三条路,因为要把上千份文档纳入 Git,我需要的是能够明确报错、可中断、可重跑、可回归的转换流程,而不是“大部分转出来就行”的批处理脚本。
3. 拆开 DOCX 看真相:一个带了一屋子附件的 ZIP 文件夹
3.1 三步解剖一个最小 DOCX 文件
如果只用 python-docx 做转换,不深究 DOCX 内部结构其实也能跑通,但一旦遇到疑难杂症,你会发现所有问题最终都要回到文件结构层面去找答案。与其到时候再补课,不如先花五分钟把它看明白。
DOCX 本质上就是一个 ZIP 压缩包,只是改了扩展名和内部协议。随便找一个最小的 docx,用解压命令打开:
你会看到类似这样的目录结构:
简单说,word/document.xml 是正文,word/media/ 是文档里嵌的所有图片,word/styles.xml 是这个文档用到的样式定义,word/numbering.xml 是列表编号规则,word/rels/document.xml.rels 则负责把正文里引用的图片、超链接等资源与真实文件对应起来。你写转换器时 90% 的时间都在跟这几个文件打交道。
3.2 document.xml 里最核心的四层嵌套标签
打开 document.xml,你会看到一堆带着 w: 前缀的标签,这是 WordprocessingML 的命名空间。对转换器来说,核心其实只有四层嵌套关系:
w:p表示一个段落,对应 Markdown 里的一个块元素的基础单位。w:pPr是段落的属性,里面记着段落的样式 ID、编号属性、对齐方式等。标题级别的判断主要看这里的w:pStyle。w:r是段落里的一个片段(run),对应你看到的连续文本和它携带的字符格式。w:t是 run 里真正的文本内容,所有文字最终都落在这一层。
举个例子,一个简单的“加粗的 Hello”在 XML 里大概长这样:
理解了这一层,后面你在写转换器时看到 python-docx 返回的对象结构就不会发懵。之所以有 w:r 这一层,是因为 Word 允许一个词甚至一个字拆成多个 run,每个 run 各自带不同的字符格式。这也是加粗斜体转换里最经典的坑,后面我会单独讲。
3.3 为什么建议用 python-docx 而不是直接解析 XML
既然 DOCX 就是 XML,那我能不能直接用 ElementTree 硬写一个解析器?能,但我强烈建议不要。原因有三个:
第一,命名空间太啰嗦。一个标签名写完整是 {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p,你每次都要写 qn() 转一下,代码全是噪音。
第二,样式继承很复杂。一个段落表面上是 Normal 样式,但它可能从文档默认样式、主题字体、直接格式里面继承了好几层属性。python-docx 已经把常用样式属性封装成 paragraph.style.name、run.bold 这样的接口,虽然不完全,但覆盖了 90% 的需求。
第三,图片关系需要跨文件查找。你从 document.xml 里看到一个 <w:drawing>,里面只存了 rId,真正的图片文件在哪,要去 document.xml.rels 里查,然后还要去 [Content_Types].xml 确认类型,最后再到 zip 包里去取文件。这一套关系解析自己写很容易出错,python-docx 的 document.part.rels 已经帮你把手脚接好了。
所以我的结论是:直接解析 XML 只适合两种场景,一是 python-docx 本身支持不了的极端格式,二是你想做一个不依赖第三方库的轻量工具。常规情况下,站在 python-docx 的肩膀上,遇到特殊问题再深入到 XML 层面去处理,是效率最高的组合方式。
4. 从 python-docx 起步:段落遍历、样式映射与 run 级格式救火
4.1 环境准备:依赖、编码和“控制台中文乱码”的第一道坎
开始写代码前,先把环境准备好。我建议在干净的虚拟环境里操作,Python 3.8 以上都可以:
装好后先跑一个最简单的读取脚本,确认 Python 能正常读取你的测试文档:
很多人在这里就会遇到第一道坎:终端打印中文时输出乱码,或者直接抛 UnicodeEncodeError。这不是 python-docx 的问题,而是 Windows 控制台默认编码在作怪。如果你用的是 Windows,建议在脚本最前面加上:
或者在写入文件、打印日志时统一使用 UTF-8 编码。我见过不少人卡在“只说乱码,不说具体报错”的阶段,其实把编码理顺之后,后面一切都会顺很多。
4.2 段落级转换:标题、正文、列表的映射逻辑
python-docx 的 doc.paragraphs 只包含文档顶层的段落,不包括表格里面的段落。如果你直接拿它遍历,表格内容会整个消失。所以我用了一个经典的迭代器,按文档流顺序把段落和表格都找出来:
如果你需要递归处理表格内部的嵌套段落,把 cell 作为 parent 再次调用 iter_block_items 即可。拿到一个段落之后,核心就是按样式名做映射。我的大致规则是这样的:
注意这里面有几个业务决策点。一是“标题级别”到底取哪个数字,不同模板可能把一级标题命名为 Heading 1,也可能命名为 标题 1,更复杂的还有 Heading 1 Char 这种字符样式。稳妥的做法是先跑一遍统计出这个文档集里实际出现过的样式名,再写映射表,而不是在代码里硬编码几种英文名。二是列表项,python-docx 会把手动编号按普通正文读出来,我们在这一层只处理用原生样式标记的列表,手动编号的“假列表”放到后面单独清理。
4.3 run 级细节:加粗斜体在 Word 内部的“分身术”
段落文本用 para.text.strip() 拿很快,但这样拿到的文本丢掉了加粗、斜体等行内格式。要想在 Markdown 里恢复 **加粗** 和 *斜体*,必须深入到 run 级别去处理。
这里最容易踩的第一个坑,就是 Word 会把一个视觉上连续的加粗句子拆成多个 run。比如“这是加粗的标题”这个短语,可能第一个 run 是“这是”,后面因为拼写检查或样式继承,第二个 run 才是“加粗的标题”,每个 run 都有加粗属性,但从代码角度看它们是两个东西。如果仅仅按 run 单独判断、单独输出,你最终会得到类似 **这是****加粗的标题** 这种断裂的标记,渲染出来虽然看着差不多,但一旦中间插了空格或换行,就非常难看。
我的处理思路是:遍历 run 时先记录每个 run 的格式特征,把相邻且格式相同的 run 合并成一个逻辑片段,再统一包裹标记:
这个函数不复杂,但能解决绝大多数行内格式问题。还有一点要注意:run.bold 可能是 None,表示继承段落或文档的样式定义,不要简单显式地把它当 False 处理,否则继承的加粗会丢。如果文档里大量依赖样式继承,那就要先把段落样式里的加粗属性也合并进来,再往下传到 run 处理。
4.4 超链接与特殊段落:不是每次都能走捷径
python-docx 里处理超链接比较绕,因为它把超链接的显示文本放在 <w:hyperlink> 标签内部的 w:r 里,而 para.runs 默认不包含这些 run。我一开始直接用 para.text 拿链接文本,发现链接文字还在,但链接地址完全拿不到。
正确的方式是通过 para.hyperlinks 访问:
但由于普通 run 和 hyperlink 中的 run 是分离的,要把“这一段里既有普通文字又有超链接”完整拼出来,需要自己维护顺序。我采取的是一种简单粗暴但有效的方法:遍历 para._element 的直接子元素,判断是 w:r 还是 w:hyperlink,分别处理。这个过程代码量不大,却很容易被忽略,我这里就不展开完整实现了,你只需要记住“链接文本和普通文本要按 XML 子元素顺序合并”,后面遇到对应问题就不会懵。
5. 表格、图片、代码块:三个最容易让转换器破功的元素
5.1 表格:Markdown 语法要求每行等宽,而 Word 表格是自由的
Markdown 表格语法很严格,每一行用 | 分隔的单元格数量必须一致,否则渲染器直接摆烂。而 Word 表格从来不拘小节:可以合并单元格,可以某一行的列数比别人多,还可以嵌套表格。这两个工具之间的落差,是表格转换最核心的矛盾。
对于没有合并单元格的简单表格,转换逻辑很直接:
但一旦遇到合并单元格,这个方法就会出问题:python-docx 遍历 row.cells 时,纵向合并的单元格会在多行里反复出现,导致同一段文本在 Markdown 表格里被复制粘贴好几遍;横向合并的单元格则会让某一行的列数比其他行少,直接破坏表格结构。
我的处理方式是先过滤重复的单元格。用 cell._tc 这个底层 XML 元素作为去重键,只保留第一次出现的实例:
这样处理后,纵向合并的文本不会重复,横向合并后的空缺在 Markdown 里没法完美表达,但至少不会把整张表搞乱。如果你的表格里有更复杂的合并逻辑,我的建议是:把这张表降级为纯文本形式,保留单元格内容顺序,放弃表格结构,总比转出一张渲染错乱的表格要强。
5.2 图片:把 media 导出到本地,再改引用路径
Word 里的图片管理逻辑是:正文中通过 rId 引用一个资源,真正的图片文件存在 word/media/ 下。python-docx 可以把图片 blob 取出来,但更稳定、更简单的做法是直接用 zipfile 读取整个 docx,把 word/media/ 下的文件全部导出到目标目录:
为什么推荐这样而不是遍历 doc.part.rels?因为纯 zipfile 操作不依赖 python-docx 对关系的加载,遇到异常文档时容错更好;而且 DOCX 体积通常不大,把 media 整个目录抽出来是很快的。
图片导出之后,还需要在 Markdown 里给每个引用位置拼正确的路径。最简单的方式是在转换正文时,遇到 <w:drawing> 就解析出它的 rId,再通过关系表找到对应的图片文件名,输出 。解析 drawing 的简要思路是:
拿到 rId 后,用 doc.part.related_parts[r_id] 就能拿到对应的图片 part,进而取得文件名和 blob。这条路一开始看起来繁琐,但一旦走通,所有图片引用都会变得非常可靠。
还要提醒一个特别容易踩的坑:Word 文档里的图片不一定是 PNG 或 JPEG,很多老文档嵌的是 EMF、WMF 这种矢量格式。Markdown 阅读器大多数不支持直接渲染,转换后你需要先把它们批量转成 PNG。我这边是用 LibreOffice 命令行批量处理:
Windows 上如果装了 LibreOffice,soffice 在安装目录的 program 文件夹里,记得把它加到 PATH 里再跑。
5.3 代码块:从样式名和字体特征去识别,而不是猜语言
DOCX 里其实没有“代码块”这种语义概念,只有“应用了某种样式或某种字体的一段文字”。所以我识别代码块用的是两条规则的组合:
- 段落样式名里包含 Code、Source、源码、代码 这类关键词;
- 段落使用的字体名是 Consolas、Courier New 或其他等宽字体。
命中其中一条,我就把这个段落输出为围栏代码块:
注意,Word 里没有记录代码的语言类型,转出来的代码块默认不带高亮语言标识。如果文档集里代码语言很固定(比如全是 SQL),你可以通过文件名、上下文关键词做简单猜测;否则就统一输出成无语言的围栏代码块,让后续编辑时人工补。千万别尝试在转换器里用一堆正则去猜语言,样本一多必然误判,代码块渲染出来比不渲染还难受。
6. 真实业务文档里踩过的四个坑,以及完整的排查思路
6.1 坑一:连续空段落把 Markdown 挤成一坨空白
我跑完第一批五十份文档后,打开生成的 Markdown 文件,发现好多地方出现大段空白,有的地方隔着十几行空行才看到下一段正文。一开始以为是转换器 bug,后来一查才发现罪魁祸首是原文里就连着七八个空段落。
Word 里很多人习惯用空段落“撑开”排版距离,这属于常见操作。但空段落到了 Markdown 里就是空行,一两处还行,七八处连在一起就直接把内容顶散了。我的解决办法是:在输出时压缩连续空行,合并成一个段落分隔符;同时在每份文档内部设定“连续空白超过三行就截断”的规则。
排查思路也分享给你:遇到空白异常,先别急着改代码,把生成的 md 和原 docx 并排打开,看空白是均匀分布在页面底部,还是固定在某个结构元素之后。后者通常意味着是表格或者图片后面的空段落被原样输出了,处理起来更有针对性。
6.2 坑二:手动编号加制表符造成的“假列表”
第二份样本让我更头疼。文档里大面积出现这种内容:
看起来是有序列表,但实际上每个段落都是普通正文样式,只是行首输入了“1.”“1.1”“2.”,以及一串手打的空格或制表符。python-docx 里它们的 style 全是 Normal,所以我的转换器把它们全部输出成了普通段落,列表层级信息在 Markdown 里完全丢失。
这个问题没有特别简单的库函数能解决,必须写启发式逻辑。我最终采用的规则是:
- 如果段落文本以数字加
.或、开头,再跟空格,视为有序列表项; - 判断该段落与前一段的文本缩进情况,如果前一段顶部空格更多,则视为子列表;
- 如果段落以
-、•、*加空格开头,视为无序列表项; - 开头符号后面如果跟着的完全是中文且没有编号递增规律,降低识别置信度,宁可当普通段落也不要误判。
启发式规则没法做到 100% 准确,所以我在转换器里加了一个“不确定列表”日志,专门把命中低置信度规则的段落打印出来,人工扫一遍再决定要不要调整阈值。这种做法在批量场景里比追求完美算法更务实。
6.3 坑三:Windows 下文件编码导致的乱码
这其实不是 DOCX 特有的坑,但在 Windows 环境下批量转换时特别容易碰到。我在一台 Windows 服务器上跑批处理,输出日志里中文乱码,生成的 md 文件用记事本打开没事,但用某些脚本读取时却报编码错误。
排查链路是这样的:先看 Python 进程的输出编码,发现控制台默认用 GBK,重新配置成 UTF-8 后日志正常了;再看写入文件时是否指定编码,我最初用 open(md_path, "w") 没有指定 encoding,Python 会按 locale 默认编码写入,在中文 Windows 上就是 GBK。后来全部改成:
同时把读文件的代码也统一加上 encoding="utf-8",问题就彻底消失了。这里有个经验:处理文本文件时,读写两侧都要显式指定编码,不要依赖默认值。你的脚本在 Linux 上默认 UTF-8 没问题,一跨到 Windows 就翻车,基本全是这个原因。
6.4 坑四:合并单元格在表格里反复“分身”
表格合并的问题我在 5.1 里提过,这里说一个更隐蔽的情况。有些文档的合并单元格在 python-docx 里重复出现不是简单的“同一行里两次”,而是纵向合并后每一行都会遍历到同一个 _tc。我最初发现输出的 Markdown 表格里某列内容反复出现,比如“总计 100 元”出现了四行,还以为是文本提取错了,差点去查 python-docx 的源码。
后来在调试过程中我打印了每个单元格对象的内存地址,发现合并单元格在 row.cells 里本来就是同一个对象重复返回。明白了这一点,解决方案就很清晰:用 cell._tc 做全局去重键,第一次遇到就输出,后面遇到跳过。这个 bug 的启示是:遇到“内容重复”的问题,不要先怀疑文本解析,先检查是不是元素引用关系导致的重复遍历,这个方向能帮你省下不少时间。
跑完这一千多份文档之后,我对“用 Python 把 DOCX 转成 Markdown”这件事有了完全不同的理解:真正的难点从来不在转换算法本身,而在于面对不可控的文档格式时,你能不能把问题拆成“可逆的结构问题”和“不可逆的录入习惯问题”两类。前者用代码解决,后者用规则和人工抽检解决。我最后再分享一个很实用的经验:给转换器配一套回归样本。我从全部文档里挑出十份格式差异最大的样本,每次改动转换逻辑后都跑一遍,对比输出 diff,确保“修好一个新问题”的同时不会“搞坏两个旧场景”。这套做法看起来笨,但在一千份文档的批量场景里,比什么都管用。如果你也要做同类项目,建议从第一天就把它加进你的流程里。