MarkItDown：一条命令把 15+ 种文件转成 Markdown

MarkItDown：一条命令把 15+ 种文件转成 Markdown

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

MarkItDown 是微软的 Python 工具，把 PDF、Word、Excel、PPT 等文件转成保留结构的 Markdown。它解决喂给 LLM 和文本分析流水线前的文档预处理问题，适合要把异构文档批量接入 RAG、语义检索或文档问答系统的开发者。

看懂 MarkItDown 支持的 15+ 种文件格式

它既是读文件输出 Markdown 的命令行工具，也是可嵌入流水线的 Python 库。官方列出的支持格式分四类：

• 办公与文档：PDF、DOCX、PPTX、XLSX（含旧版 XLS）、EPub
• 网页与文本：HTML、CSV、JSON、XML、RSS、Wikipedia
• 媒体：图像（EXIF 元数据 + LLM 图像描述）、音频（元数据 + 语音转录）
• 容器与来源：ZIP（递归处理）、YouTube URL 字幕提取

每种格式对应独立转换器，通过 pip 可选依赖组按需安装。

上图为仓库测试文件中用作转换示例的论文 PDF，这类内容可被转成带标题层级的 Markdown。

🚀 一条命令完成 MarkItDown 安装与转换

环境要求 Python 3.10–3.14。安装：

pip install 'markitdown[all]'

[all]会装全格式依赖，最小化安装可只装所需项，如pip install 'markitdown[pdf, docx]'。命令行用法：

markitdown report.pdf -o report.md

输出保留标题层级、表格和链接，也支持管道：cat report.pdf | markitdown。Python API：

from markitdown import MarkItDown print(MarkItDown().convert("report.xlsx").markdown)

读懂 MarkItDown 的转换结果：标题、表格与链接

它与传统文本提取工具的区别在于保留结构：标题变成#–######，Word/Excel 表格变成 Markdown 表格，列表保留项目符号，超链接和图片引用写成标准 Markdown 语法。

这是有意为之：主流 LLM 对 Markdown 的表现好，且其 token 占用低。所以输出是"人能读，但为机器优化"。

🧩 三种扩展方式：插件、LLM 描述、MCP 服务器

• 第三方插件：不改主包即可新增格式。官方markitdown-ocr用 LLM Vision 提取 PDF/DOCX/PPTX/XLSX 内嵌图片文字，markitdown --use-plugins启用。
• LLM 图像描述：传入llm_client与llm_model后，转换 PPTX/图像时会调用视觉模型生成图片描述，让图片内容也进入文本。
• MCP 服务器：markitdown-mcp包把转换封装成 MCP 工具convert_to_markdown(uri)，直接暴露给本地 agent。

进阶选项集中在此：可选依赖组（如[audio-transcription]）、Azure Document Intelligence / Content Understanding 云转换、Docker 部署。

对比 MarkItDown、pandoc 与 textract

维度	MarkItDown	pandoc	textract
格式覆盖	✅ 15+，含音频/图像/YouTube	✅ 约 20 种文档类型，无音频	⚠️ 以文档和图片为主
结构保留	✅ 标题/表格/列表	✅	❌ 纯文本
面向 LLM	✅ 输出为 LLM 设计	❌ 需后处理	❌
媒体转换	✅ 音频转录、图像描述	❌	部分
扩展性	✅ 插件系统 + MCP server	❌	❌
上手成本	✅ 单条 pip 命令	⚠️ 需单独安装二进制	❌ 依赖重、版本易漂移

两个真实用法：RAG 知识库与 agent 文件读取

搭建 RAG 知识库：接入 PDF/DOCX/PPTX 混杂的历史文档时，先用 markitdown 批量转 Markdown，保留标题层级和表格，再切块索引。转换环节是一条命令，不用为每种格式写解析代码。

给 agent 加文件读取能力：运行markitdown-mcp作为 MCP server（默认只绑定 localhost），agent 调用convert_to_markdown(uri)即可读本地文件或远程 URL，输出统一为 Markdown。

⚠️ 避坑：四个需要预先了解的边界

1. 不面向人类高保真显示：官方 README 明确输出面向文本分析工具，若要还原原版式应选专用转换工具。
2. 部分功能依赖环境：EXIF 元数据需要exiftool程序，音频转录需要语音识别依赖；缺依赖时对应内容被跳过而不是报错。
3. 云服务按次计费：走 Azure Document Intelligence / Content Understanding 的每次转换都是计费 API 调用，可用cu_file_types限定路由范围。
4. 不可信输入有安全风险：MarkItDown 以当前进程权限做 I/O。服务端场景应先校验文件路径与 URL，并调用最窄的convert_local()/convert_stream()，而不是宽松的convert()。

小结

MarkItDown 定位是 LLM 的文档预处理层：格式覆盖广、保留结构、可插拔扩展，还自带 MCP server。要给人看的高保真排版它不是合适选择；要喂给模型文档，一条 pip 命令就能开始。

• 项目文档：README.md
• 许可证：LICENSE（MIT）

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown