微软开源MarkItDown：一行代码把PDF/Word转成干净Markdown

今天 GitHub 热点项目 MarkItDown 一天涨了 14 万颗星，把我都看愣了。微软开源的一个 Python 工具，能把 PDF、Word、Excel、PPT、图片甚至压缩包里的文件转成 Markdown。听起来像 Pandoc 的简化版？但用下来发现它有几个让我真香的特性，也有些明显短板。这篇文章会把它的核心功能、代码示例、跟 Pandoc 的对比、落地中的坑都说清楚，你读完应该能在 10 分钟内决定要不要集成到自己的项目里。

python code editor showing markitdown conversion

为什么需要这么个工具？

做后端或者数据处理的朋友应该都遇到过这个问题：需要把用户上传的 Word 文档、PDF 报表或者 Excel 表格的内容提取出来，塞进搜索引擎、大模型或者知识库。传统做法是用 Pandoc（命令行依赖重）、用 python-docx/pdfminer.six 各自写解析逻辑，遇上图片里的文字还得单独接 OCR。维护一套多格式转换脚本，比写业务代码还痛苦。

MarkItDown 做的就是：你给它一个文件路径或者字节流，它返回一个 Markdown 字符串。统一接口，减少心智负担。虽然它依赖部分第三方库，但安装时按需拉取，不会像 Pandoc 那样要单独装引擎。

能转哪些格式？

官方支持的格式列表：

  • PDF（.pdf）
  • Word（.docx）
  • Excel（.xlsx，.xls）
  • PowerPoint（.pptx）
  • 图片（.jpg，.png 等，通过 Azure AI 服务做 OCR）
  • HTML（.html，.htm）
  • CSV（.csv）
  • JSON（.json）
  • XML（.xml）
  • 压缩包（.zip，会自动递归解压其中文件）
  • 甚至还有 .msg 邮件？实测只支持 Outlook 的 .msg，但非 Windows 下依赖 msgparser 库可能不稳。

注意：图片 OCR 需要你有一个 Azure AI Document Intelligence 的 API Key，是付费服务。如果你不想用云，可以自己替换成 Tesseract 本地 OCR（后面我会给扩展例子）。

最少代码演示

安装：

bash
1 
pip install markitdown

如果你要转 PDF，需要额外装 pdfminer.six：

bash
1 
pip install markitdown[pdf]

同样，Excel 需要 openpyxl，PowerPoint 需要 python-pptx，但安装时可以一次装完：

bash
1 
pip install markitdown[all]

然后写一段最简单的转换代码：

python
1 2 3 4 5 
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("example.docx")
print(result.text_content)

就这么简单。对于 PDF，同样一行：

python
1 2 
result = md.convert("report.pdf")
print(result.text_content)

它会自动识别文件类型，然后调用对应的解析器。

如果你要处理图片文字，需要配置 Azure 客户端：

python
1 2 3 4 5 6 7 8 9 10 
from markitdown import MarkItDown
from markitdown.ocr import AzureAIDocumentIntelligenceClient

ocr_client = AzureAIDocumentIntelligenceClient(
    endpoint="https://<your-resource>.cognitiveservices.azure.com/",
    credential="<your-api-key>"
)
md = MarkItDown(ocr_client=ocr_client)
result = md.convert("invoice.jpg")
print(result.text_content)

和同类方案的对比

对比 Pandoc

Pandoc 是文档转换的瑞士军刀，支持格式几十种，输出除了 Markdown 还有 LaTeX、HTML、PDF 等。但它的使用方式通常是命令行，要在 Python 里调用得用 subprocess 或 pypandoc，并且需要系统里安装好 Pandoc 本身。对于容器化部署或者 CI/CD 来说，多一个二进制依赖就多一个维护点。而且 Pandoc 对 PDF 的转换依赖 LaTeX 引擎（如 pdf2latex 或 wkhtmltopdf），生成 Markdown 时并不会做 OCR。

MarkItDown 是纯 Python 库，通过 pip 安装，不依赖外部二进制（除了 PDF 需要 pdfminer.six，但也是纯 Python）。API 设计更 Pythonic：md.convert(file) 直接返回对象，属性清晰。

MarkItDown 赢在：轻量、无系统依赖、统一接口。

Pandoc 赢在：输出格式丰富、自定义性强、成熟稳定。

如果你只需要把办公文档转成 Markdown 喂给 LLM，选 MarkItDown；如果你需要从 Markdown 转成 Word/LaTeX/PDF（反向转换），或者需要复杂的模板定制，还是 Pandoc。

对比 python-docx / PDFMiner / openpyxl 自己写

自己写优点是灵活，比如你可以精确控制表格怎么渲染、段落编号怎么保留。缺点是每种格式一套代码，测试维护成本高。而且 PDF 中的图片文字几乎是盲区。MarkItDown 在这些格式上的转换质量，我实测下来：

  • Word 转 Markdown：段落、标题、加粗斜体、列表都保留得不错，表格变成简单的 Markdown 表格（不包含合并单元格）。
  • PDF 转 Markdown：基本是纯文本提取，排版丢失很多（PDFMiner 的先天缺陷），图片直接忽略（除非开 OCR）。
  • Excel 转 Markdown：每个 sheet 成一个 H2 标题，下面一个表格，第一行是表头。够用，但公式结果可能不准确（依赖 openpyxl 的 data_only 参数，如果你保存时没存值会读出 None）。
  • PPT 转 Markdown：每一页一个 H2，提取标题、正文、备注，图片不处理。

terminal showing markitdown conversion result for word document

适用场景与局限

适用的场景

  1. LLM 数据预处理：把各种格式的文档统一成 Markdown 后切块，喂给 RAG 系统或微调模型。我自己项目里拿它处理一仓库的 Word 合同和 PDF 规格书，效果比之前用 python-docx + pdfminer 自己搭的管线稳定很多。
  2. 文档内容搜索：给企业内部的文档建索引，转成 Markdown 存入 Elasticsearch 或文心。
  3. 文本分析：比如统计文档关键词、情感分析，直接用 Markdown 文本即可。
  4. 日志/报告生成：把 Excel 和 PPT 内容提取后自动摘要。

局限和坑

  1. 图片 OCR 必须联网且付费：Azure AI Document Intelligence 按页面收费，如果你要处理大量含图片的 PDF，成本需要考虑。好在可以自己写一个本地 OCR 插件，用 Tesseract 替换（但需要安装 tesseract 二进制）。下面我会给一个简化的自定义 OCR 示例。
  2. 表格提取质量一般：对于复杂表格（合并单元格、不同背景色、带图片的单元格），MarkItDown 只会输出简单的 Markdown 表格，会丢失单元格跨度、样式等信息。如果你需要保留原始表格结构，还是得用专门的库如 camelot（PDF 表格）。
  3. 公式：Word 里的 MathType 或 LaTeX 公式，PDF 里的公式符号，基本没有正确提取。MarkItDown 不支持。
  4. 中文支持依赖底层库：PDF 用 pdfminer.six，它对中文 PDF 提取有时会乱码（需要安装正确字体）。Word 和 Excel 的 openpyxl/python-pptx 对中文友好，没问题。
  5. 性能：转换大的 PDF（几百页）时，速度比专业商业工具慢 2-3 倍。毕竟 pdfminer.six 不是为速度优化的。

自定义 OCR 插件示例

如果你不想用 Azure，可以模仿它的接口做一个本地 Tesseract OCR 版本：

python
1 2 3 4 5 6 7 8 9 10 11 12 13 
from markitdown.ocr import OCRClient
import pytesseract
from PIL import Image

class TesseractOCRClient(OCRClient):
    def recognize(self, image_bytes: bytes, **kwargs) -> str:
        from io import BytesIO
        image = Image.open(BytesIO(image_bytes))
        text = pytesseract.image_to_string(image, lang='chi_sim+eng')
        return text

ocr = TesseractOCRClient()
md = MarkItDown(ocr_client=ocr)

注意：你需要先安装 tesseract-ocr 和 pytesseract，并下载中文语言包。这个插件可以用，但识别质量不如 Azure 云服务，特别是手写体或低分辨率图片。

快速上手步骤

  1. 创建虚拟环境并安装：
    bash
    1 2 3 
    python -m venv .venv
source .venv/bin/activate
pip install markitdown[all]  # 装所有格式支持
  2. 准备一个测试文件（比如 test.docx），然后在同一目录下创建 run.py：
    python
    1 2 3 4 
    from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.docx")
print(result.text_content[:500])
  3. 运行 python run.py，看看输出。
  4. 如果需要处理图片，参考上面配置 Azure 或自定义 OCR。
  5. 批量转换：遍历目录，对每个文件调用 convert，写文件。
python
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 
import os
from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
input_dir = Path("./docs")
output_dir = Path("./markdown_output")
output_dir.mkdir(exist_ok=True)

for ext in ["*.pdf", "*.docx", "*.pptx", "*.xlsx", "*.html", "*.csv"]:
    for file in input_dir.glob(ext):
        result = md.convert(file)
        out_path = output_dir / f"{file.stem}.md"
        out_path.write_text(result.text_content, encoding="utf-8")
        print(f"Converted {file.name} -> {out_path.name}")

我的看法

MarkItDown 火起来不是因为技术有多颠覆——它本质上是对已有 Python 库的封装加了一点点微软的云集成。但它做对了一件事：把“把各种文档变成 Markdown”这个高频需求暴露成了一个极其简单的 API。对于 80% 的场景，这已经够了。剩下的 20%（复杂表格、公式、高保真排版）可能需要专业工具，但你不能指望一个开源库什么都做。

如果你已经在用 Pandoc 或者自己拼 parser，迁移过来是否值得？我的建议是：

  • 如果你只需要单向转换（文件→Markdown），MarkItDown 绝对更省心。
  • 如果你还需要反向转换（Markdown→其他格式），或者需要自定义输出模板，继续用 Pandoc。
  • 如果你对图片 OCR 有强需求但不想用云，用上面给的 Tesseract 替换方案，但要接受质量下降。

最后，别忘了这个项目是 MIT 协议的，商用无压力。微软开源又一枚好用的齿轮，至于它能不能变成你工具箱里的常驻工具，取决于你的文档有多“规矩”。如果都是标准排版、无复杂格式，大胆上。如果天天和那种调格式像调酒一样的奇葩 PDF 打交道，建议先跑一波测试。

comparison table of markitdown vs pandoc vs manual

我已经在自己负责的数据管线里把它替换掉了之前的 pandas + pdfminer 组合，代码量从 200 行缩到 10 行。希望你也能找到适合自己的用法。