用Python把PDF/Office转Markdown，微软开源这个工具能省多少事

上周在GitHub扫到一个叫 markitdown 的项目，今天已经飙到 13 万 star。微软出品，作用是把你手头的各种文档——Word、Excel、PPT、PDF、HTML、图片里的文字——统统变成 Markdown。

作为后端开发，我经常要处理用户上传的简历、合同、报告，提取全文做全文搜索或者喂给 LLM。之前这活都得自己撸：PDF 用 PyMuPDF 或 pdfplumber，Word 用 python-docx，然后格式还乱得一塌糊涂。这个工具号称“一站式”，我立刻试了试。

markitdown conversion example screenshot

它解决了什么问题

开发中常见场景：你有一个文档（比如 .docx 或 .pdf），需要把它转成 Markdown 格式，方便后续存入数据库、做全文索引，或者直接送给 ChatGPT 做摘要。传统做法是每种格式写一种解析器，然后自己拼格式，代码又臭又长。

markitdown 封装了多种解析引擎，对外提供同一个接口：输入文件路径，输出 Markdown 字符串。

python
1 2 3 4 5 
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("resume.docx")
print(result.text_content)  # Markdown 格式的文本

就这么简单。convert 方法自动根据文件后缀选择解析器，回传一个对象，里面除了 text_content 还有 metadata（文档属性）。

核心功能与代码示例

1. 支持的格式

当前（2025 年 3 月）支持：

  • Word (.docx)
  • Excel (.xlsx, .xls) — 会把每个 sheet 转成表格
  • PowerPoint (.pptx) — 提取每张 slide 的文本和备注
  • PDF (.pdf) — 依赖 PyMuPDF（fitz）
  • HTML (.html, .htm)
  • 图片 (.png, .jpg 等) — 通过 OCR，默认用 pytesseract
  • 纯文本 (.txt, .csv)
  • 富文本 (.rtf)

2. 表格处理

Excel 转 Markdown 时，markitdown 会把每个 sheet 输出为 Markdown 表格。来看一段真实输出（我拿一个 3 行 4 列的产品表测试）：

markdown
1 2 3 4 5 6 
## Sheet1
| Product | Price | Quantity | Note |
| --- | --- | --- | --- |
| Widget A | 10.99 | 100 | Best seller |
| Widget B | 24.99 | 50 | New |
...

比起 python-docx 手动拼表，省了至少 20 行代码。

3. PDF 转 Markdown（并保留标题层级）

PDF 是最头疼的格式，因为布局信息容易丢失。markitdown 用 PyMuPDF 提取文本，并尝试根据字体大小/加粗来推断标题级别。实测一份 10 页的会议纪要，识别准确率大约 70%——标题基本对了，但列表有时会被当成普通段落。

python
1 2 3 
result = md.convert("meeting_minutes.pdf")
with open("output.md", "w") as f:
    f.write(result.text_content)

pdf to markdown title hierarchy comparison

4. 图片 OCR

给一张含文字的截屏，markitdown 会调用 tesseract 识别文字。默认只提取文本，不保留图片本身到 markdown 里。如果你需要把图片嵌入 markdown（比如 alt），得自己再加工一下——它只返回 OCR 文本。

和同类项目的区别

我对比了目前常用的两个方案：

特性 markitdown pypandoc unstructured
安装复杂度 简单（pip install） 需要 pandoc 本体 + 额外包 需要安装 tesseract、poppler 等系统依赖
格式支持 Office + PDF + 图片 极多格式（ldoc、latex、epub等） PDF、图片、Office、邮件等
输出质量（PDF） 中等（尽量推断标题） 无特殊处理（标题可能丢失） 高（带 layout 分析）
是否保留表格 是（Markdown 表格） 是（依赖 pandoc 解析） 是（但有时拆成普通文本）
学习成本 低（一个类） 中等（要用命令行或 binding） 中等（需要理解 partition 不同文档类型）
依赖重量 轻（几个 Python 库） 中（需要系统安装 pandoc） 重（OCR、NLP 模型等）

我的判断： 如果你只是想把 Office 文档或简单 PDF 转成 Markdown，markitdown 是最省事的。它不要求你装系统级工具（除了 OCR 需要 tesseract），pip 完直接跑。如果你需要处理复杂排版的学术论文 PDF（双栏、复杂表格），unstructured 的 partition_pdf 更合适，但代价是安装时间可能半小时起步。

适用场景与局限

✅ 适合

  • 文档内容提取：给 RAG 系统喂数据，把公司内部的 Word/PDF 文档转成 Markdown 再分块。
  • 批量格式转换：写一个脚本，把一堆 .docx 转 .md，方便 git 版本管理。
  • 快速 prototyping：要用 LLM 处理邮件附件，不想自己写解析器。

❌ 不适合 / 坑

  • 复杂 PDF 排版：双栏、多级标题、嵌入表格、页眉页脚——markitdown 基本放弃。它只是简单提取文本，然后用 heuristic 推断标题。如果原文是扫描件（图片式 PDF），必须依赖 OCR，但 OCR 结果没有坐标信息，顺序可能错乱。
  • 保留原始布局：你想把 PDF 精确还原为 Markdown 表格+图片位置？不行，它只做纯文本提取。
  • 超大文件：一个 500 页的 PDF 会全部读入内存，然后逐页处理，耗时和内存都不是最优。我没测极限，但建议超过 200 页先分块。
  • 依赖版本敏感：markitdown 底层用 PyMuPDF、python-docx、openpyxl 等，这些库的版本兼容问题可能偶尔踩坑，记得锁定版本。

快速上手步骤

  1. 安装 Python 3.9+ 环境
  2. pip install markitdown
  3. 写一个脚本：
python
1 2 3 4 5 6 7 8 9 
from markitdown import MarkItDown

md = MarkItDown()
files = ["report.docx", "data.xlsx", "slide.pptx", "meeting.pdf"]
for f in files:
    result = md.convert(f)
    print(f"=== {f} ===")
    print(result.text_content[:200])
    print("---")
  1. 如果要用 PDF 或图片 OCR，可能需要额外安装 pytesseract 和 tesseract-ocr 系统包（macOS: brew install tesseract；Ubuntu: sudo apt install tesseract-ocr）

最后说两句

markitdown 不是银弹，但它在“快速把 Office 文档变成可读的 Markdown”这件事上做到了极简。如果你项目里很多用户上传的是 .docx 而不是 PDF，它几乎零成本集成。但如果上游全是复杂 PDF，建议还是花时间配 unstructured。

别被 13 万 star 忽悠——微软的 repo 经常因为好奇刷上去，实际值不值得用取决于你的具体文档类型。先拿几份真实文档测跑一遍，最坏情况也就损失 10 分钟 pip 时间。