用微软MarkItDown把文档转Markdown，值不值？

今天 GitHub 热榜第一是微软的 MarkItDown，一天涨了13万star。我第一反应是：又一个转换工具？但看到是微软出的，还是忍不住点进去看了。看完感觉：这玩意儿批量转换 Office 文档确实挺香，但别指望它搞定 PDF 和图片里的复杂排版。

它解决了什么问题

日常开发中经常需要把 Word、PPT、Excel 甚至 PDF 转成 Markdown 格式，方便写文档、喂给 LLM 或者做知识库。以前我都是用 pandoc 一条命令搞定，但 pandoc 对中文支持一般，表格和图片处理也偏基础。MarkItDown 定位就是“通用文档转 Markdown”，而且原生支持图片 OCR（调用 Azure 服务）和表格提取。

核心功能与代码演示

安装极其简单：

bash
1 
pip install markitdown

然后几行代码就能把文件转成 Markdown 字符串：

python
1 2 3 4 5 
from markitdown import MarkItDown

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

支持的文件类型官方列了一大串：.docx, .pptx, .xlsx, .pdf, .jpg, .png（通过 OCR）, .html, .csv, .json, .xml, .zip 等等。实测一个10页的 Word 文档（含表格和图片），转换后表格结构保留得比 pandoc 好，图片链接用了 base64 内嵌（默认行为，也可以改成引用本地文件）。

需要 OCR 的话要配置 Azure 密钥：

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

ocr_engine = AzureOCREngine(
    endpoint="https://your-endpoint.cognitiveservices.azure.com/",
    key="your-key"
)
md = MarkItDown(ocr_engine=ocr_engine)
result = md.convert("screenshot.png")

如果不用 OCR，图片文件只会输出文件名和尺寸，不会提取文字。这一点对有大量截图要处理的项目需要留意。

markitdown python convert word to markdown example

和同类项目的区别

我拿 pandoc 做了对比测试（pandoc 3.1.11，MarkItDown 0.1.0）。同一份含嵌套表格的 Word 文档：

  • 表格支持：pandoc 把嵌套表格展平了，MarkItDown 保留了嵌套结构（但层级嵌套超过3层会丢失部分边框）。
  • 图片处理：pandoc 默认把图片转成相对路径；MarkItDown 默认 base64 内嵌，导致输出文件很大（一个6图的文档从5KB膨胀到2.3MB）。但可以通过设置 extract_images=True 将图片存为文件。
  • 中文乱码：pandoc 对某些字体文件的 docx 转成 md 后中文变问号，MarkItDown 用 python-docx 底层处理，没有遇到乱码。
  • 性能：100页纯文本 docx，pandoc 耗时0.8s，MarkItDown 耗时1.2s。差距不大，但 MarkItDown 内存占用高约30%。

另一个竞品是 python 的 markdownify（HTML 转 md），跟 MarkItDown 不是一个赛道的，不相比。

适用场景与局限

哪些场景值得用：

  • 批量把公司积压的 Office 文档转成 Markdown，做内部知识库或搜索索引。
  • 需要从 PPT 里提取文字和标题结构（MarkItDown 对幻灯片支持很好）。
  • 已经用了 Azure 生态的团队，直接复用 OCR 服务。

哪些场景别碰：

  • PDF 里全是扫描图片且没有 Azure 服务：免费 OCR 引擎（如 Tesseract）还没有集成，PDF 转换质量对扫描件很差。
  • 对性能要求高的在线服务：base64 内嵌图片会让输出体积爆炸，且不支持流式转换（必须全量加载进内存）。
  • 复杂公式或代码块：MarkItDown 对 Word 内嵌的 OMML 公式转成 LaTeX 格式，但矩阵和物理符号经常出错。pandoc 配合 --mathjax 效果更好。

快速上手步骤

  1. 安装：pip install markitdown （Python 3.9+）
  2. 写个简单脚本转一个 .docx 文件，看输出是否符合预期。
  3. 如果涉及图片，决定是否用 OCR：不用就默认内嵌 base64 或 extract_images=True。
  4. 批量转换写个循环，注意异常处理——MarkItDown 对损坏的文件会抛异常（不像 pandoc 会跳过）。
  5. 最后用 pip freeze > requirements.txt 锁定版本，因为项目才发版，后续 API 可能有变动。

个人建议

如果团队里只用 markdown 做轻量文档、不追求完美还原 Office 格式，pandoc 够用了。但如果你需要保留较复杂的表格、而且手上正好有 Azure 额度，MarkItDown 值得一试。13万 star 多半是微软光环加成，实际功能并不惊艳，但胜在微软出品、文档全、后续可能会有持续维护。我的评价：好用但没必要神化，适合特定场景。