使用 Python 将 DOCX 转换为 Markdown

Markdown 以纯文本形式保存内容，结构标记轻量，既能被各种文档平台渲染，也能直接作为普通文本处理。在把已有文档接入文档站点、静态博客、代码仓库，或为大模型准备语料时，Markdown 往往是比 Word 更合适的中间格式：它便于版本管理、便于批量检索，也不依赖特定软件打开。

问题在于大量存量文档是 .docx 格式。手工打开、复制、重新排版成 Markdown，不仅费时，遇到几十上百个文件时几乎无法推进。

本文以 Spire.Doc for Python 为例，介绍把 Word 文档转换为 Markdown 的方法，以及同样输出为纯文本的 PDF 转 Markdown、批量转换这几类操作。整个流程的产物都是文本文件，用编辑器打开即可核对结果。

环境准备

安装 Spire.Doc 库：

pip install Spire.Doc

在脚本中引入模块：

<span>from</span> spire.doc <span>import</span> *
<span>from</span> spire.doc.common <span>import</span> *

将 Word 文档转换为 Markdown

核心操作只有两步：加载文档，然后以 FileFormat.Markdown 保存。

doc = Document()

<span># 加载 Word 文档</span>
doc.LoadFromFile(<span>"Data/ToMarkdown.docx"</span>)

<span># 转换为 Markdown 格式</span>
doc.SaveToFile(<span>"ToMarkdown_output.md"</span>, FileFormat.Markdown)

doc.Close()

FileFormat 枚举决定了输出格式，换成 Markdown 即可得到 .md 文件。段落会转换为其对应的 Markdown 结构，标题映射为 # 层级，正文保持为普通段落。

同一个 Document 对象也可以按需保存成其他格式，例如同时产出一份 docx 和一份 PDF：

doc.SaveToFile(<span>"output.docx"</span>, FileFormat.Docx)
doc.SaveToFile(<span>"output.pdf"</span>, FileFormat.PDF)

反过来，Markdown 文件也能被加载并另存为其他格式，LoadFromFile() 会自动识别 .md 后缀：

doc.LoadFromFile(<span>"Data/FromMarkdown.md"</span>)
doc.SaveToFile(<span>"FromMarkdown_docx.docx"</span>, FileFormat.Docx)

这里需要注意的是，转换的产物是纯文本，核对结果时无需打开 Word 或图片查看器，直接用文本编辑器查看 .md 文件内容即可，也便于放进版本控制里逐行比对差异。

将 PDF 文档转换为 Markdown

存量资料里除了 Word，还有大量 PDF。PDF 的转换走的是另一套接口：先构造一个 PdfToMarkdownConverter，传入源文件路径，再调用 ConvertToMarkdown() 输出。

<span>from</span> spire.pdf <span>import</span> *

inputFile = <span>"DeleteImage.pdf"</span>
outputFile = <span>"out2.md"</span>

<span># 用输入文件构造转换器</span>
converter = PdfToMarkdownConverter(inputFile)

<span># 转换为 Markdown 并保存</span>
converter.ConvertToMarkdown(outputFile)

转换行为通过 MarkdownOptions 属性调整。例如，如果只关心文字、不需要处理 PDF 里的图片，可以把 IgnoreImage 设为 True，跳过图片处理：

converter = PdfToMarkdownConverter(inputFile)

<span># 跳过对图片的处理</span>
converter.MarkdownOptions.IgnoreImage = <span>True</span>

converter.ConvertToMarkdown(outputFile)

对于以文字为主的资料，跳过图片往往能让输出更干净，也能减少转换耗时。

批量转换多个文档

单文件转换写成函数之后，批量处理就只是加一个循环。下面的例子遍历指定目录下所有 .docx 文件，逐个转换为同名的 .md：

<span>import</span> os

input_folder = <span>"documents"</span>
output_folder = <span>"markdown"</span>

<span>for</span> filename <span>in</span> os.listdir(input_folder):
    <span>if</span> <span>not</span> filename.lower().endswith(<span>".docx"</span>):
        <span>continue</span>

    doc = Document()
    doc.LoadFromFile(os.path.join(input_folder, filename))

    md_name = os.path.splitext(filename)[<span>0</span>] + <span>".md"</span>
    doc.SaveToFile(os.path.join(output_folder, md_name), FileFormat.Markdown)
    doc.Close()

保持输入输出文件名一致（只替换扩展名）便于追溯来源，也方便后续按文件名匹配原始文档。

实用提示

• Markdown 的语法表达能力有限。Word 中的文本框、多栏排版、页眉页脚、复杂表格样式等元素，在 Markdown 里没有对应的原生语法，转换后可能丢失或降级为普通段落。转换前先拿一份有代表性的文档试跑，确认关键内容的保留情况。
• 转换结果建议程序化校验。因为输出是纯文本，可以写脚本检查文件是否为空、标题层级是否正确、关键段落是否出现，这比逐个人工翻阅可靠得多。
• PDF 转 Markdown 时，源文件是文字版还是扫描版差别很大。文字版 PDF 能直接提取文字，扫描版 PDF 的内容本质上是图片，需要先做 OCR 才能得到可用的文本。
• 批量任务注意输入目录的筛选条件。Windows 下打开 Word 会生成以 ~$ 开头的临时文件，用扩展名过滤并排除这类文件，可以避免把无关文件也纳入处理。
• 处理完及时调用 Close() 释放资源，批量循环时尤其要注意，否则文件句柄会累积。

总结

本文介绍了用 Python 把文档转换为 Markdown 的方法：用 Document 加载 Word 文档后以 FileFormat.Markdown 保存，同一个对象还能按需另存为 docx、PDF 等格式；用 PdfToMarkdownConverter 配合 MarkdownOptions.IgnoreImage 处理 PDF；再用一个循环把整批文件转换完成。由于产物都是文本文件，结果核对和后续处理都可以用脚本完成，适合接入文档站点、语料整理这类批量流程。