背景：为什么我们需要另一个文档转 Markdown 的工具？

你给 LLM 喂知识库文档、迁移博客文章、或者从一堆合同里抽数据，第一件事就是先把它们转成 Markdown。

传统方案大家首选 Pandoc，功能强大但配置繁琐——要装依赖、写过滤器、调参数。尤其处理 PDF 和 Office 文档时，Pandoc 背后依靠 pandoc-pyplot、pandoc-crossref 等插件，新手容易劝退。

微软上周开源了 markitdown，今天 GitHub 上直接飙了 12 万星。我第一反应是：又是一个“把 Word 转成 Markdown”的玩具？但仔细看源码发现，它把 PDF、PPT、Excel 甚至 ZIP 压缩包都纳入了支持列表。

这篇文章我会直接把它和 Pandoc 拉到同一份文档上对比，告诉你哪些场景能省时间，哪些场景还是 Pandoc 更靠谱。

核心功能与代码示例

安装非常简单（Python 3.8+）：

pip install markitdown

然后三行代码就能把 PDF 转成 Markdown：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("example.pdf")
print(result.text_content)  # 纯 Markdown 字符串

它支持的格式包括：

实际测试一个 20 页的 Word 文档（含表格和图片）：

result = md.convert("report.docx")
# 输出长度约 15KB，表格被转成了 GitHub 风格 markdown 表格

效果出乎意料——表格边框、缩进、加粗都有保留，没有变成纯文本堆砌。

但我发现一个坑：图片处理。 默认情况下，图片只会生成一个 ![image](img_001.png) 占位符，并不会真正保存图片文件或内嵌 base64。如果你需要图片本体，得自己遍历 result.images 列表手动处理。

和同类项目的区别（重点对比 Pandoc）

我拿同一份 PDF 论文（4 页，含公式和图表）分别用 MarkItDown 和 Pandoc 转换，对比结果如下：

我的判断： MarkItDown 赢在“开箱即食”，尤其适合以下两类用户：

1. AI 数据预处理——只需要纯文本和简单结构，不需要完美还原排版。
2. 非技术编辑——让运营同事丢一个 .docx 进去直接拿到 Markdown 内容，不用教他们装 Pandoc。

但如果你需要转换学术论文（含 LaTeX 公式），或者对图片提取有要求，Pandoc 依然是更专业的选择。

另一个竞品是 pypandoc，本质是 Pandoc 的 Python 封装，灵活性类似，但依然需要本地安装 Pandoc。MarkItDown 完全 Python 原生，无系统依赖，这在 Docker 或受限环境中是个大优势。

适用场景与局限

适合的场景：

• 知识库构建：把一堆 Word/PDF 合同转成 Markdown，喂给 RAG 系统。
• 博客迁移：从老系统导出的 HTML 转成 Markdown 导入 Hugo 或 Jekyll。
• 数据清洗：批量把 Excel 报告转成 Markdown 表格，方便在 GitHub 上预览。
• 快速预览：终端上直接看 Office 文件内容（配合 cat output.md）。

明显局限：

1. 图片只是占位符：result.text_content 中图片用 ![](filename.png) 表示，但文件并不存在。你需要调用 result.images 字典手动保存。官方文档对此没有明确说明，新手容易踩坑。

2. 中文字符支持不稳定：我在测试一份中文 PDF 时，部分字符变成了乱码。原因是底层 PyMuPDF 对某些字体编码支持不够好。而 Pandoc 使用系统字体，通常不会有这个问题。

3. 没有公式支持：MathJax、LaTeX 公式全部丢失。如果你的文档是学术论文或技术手册，转换后需要手动补公式。

4. 大文件内存占用高：测试一个 100MB 的 PPTX 文件（含大量图片），内存峰值达到 2GB，因为 MarkItDown 直接把所有内容加载进了内存。Pandoc 在部分后端中可以流式处理。

5. 输出格式单一：只能输出 Markdown，不像 Pandoc 可以输出 HTML、PDF、EPUB 等。如果你需要输出多种格式，还是得用 Pandoc。

快速上手步骤（5 分钟搞定）

前提： Python 3.8+，建议新建虚拟环境。

python -m venv md_env
source md_env/bin/activate  # Windows: md_env\Scripts\activate
pip install markitdown

命令行使用：（项目也提供了 CLI）

markitdown example.docx > output.md

Python 脚本批量处理：

from markitdown import MarkItDown
import os

md = MarkItDown()
input_dir = "docs/"
output_dir = "md_output/"
os.makedirs(output_dir, exist_ok=True)

for fname in os.listdir(input_dir):
    if fname.endswith((".docx", ".pdf", ".xlsx")):
        result = md.convert(os.path.join(input_dir, fname))
        with open(os.path.join(output_dir, fname + ".md"), "w", encoding="utf-8") as f:
            f.write(result.text_content)

保存图片的例子：（官方文档没写的坑这里补上）

result = md.convert("test.pptx")
for img_name, img_bytes in result.images.items():
    with open(f"images/{img_name}", "wb") as f:
        f.write(img_bytes)

注意：result.images 不是文件路径列表，而是 {filename: bytes} 的字典。

总结（不讲废话）

MarkItDown 适合快速把 Office 和 PDF 转成 Markdown，尤其是给 AI 喂数据或做简单迁移的场景。它比 Pandoc 更容易上手，但在图片、公式、中文支持上有明显短板。

我的建议： 如果你的需求就是“把文档变成纯文本+简单表格”，直接上 MarkItDown。如果你需要高质量还原排版、公式或图片，老老实实用 Pandoc。

项目地址：https://github.com/microsoft/markitdown

你可以在自己的工作流里先试跑一个小任务，10 分钟就能判断它好不好用。