markitdown 实战：一条命令把 PDF、Word、EPUB 转成 Markdown
项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown markitdown 是微软开源的 Python 转换工具：把 PDF、Word、PPT、Excel、EPUB、图片、音频等文件转成保留结构的 Markdown。读完能装好它、跑通第一条转换命令，并知道它在各类任务场景里的边界。
🎯 该不该上它
适合
- 文档要进大模型问答或知识库：输出是大模型原生消费的 Markdown，token 成本低
- 文件不能出本地：默认转换路径完全离线，不经过任何服务器
- 批量整理 Office 文档：一个 shell 循环转完整个目录，输出同名 .md
不适合
- 像素级排版还原：官方定位是文本分析，不是二次出版
留意
- 扫描版 PDF：内置转换器只读文字层，需加 OCR 插件或接云端端点
- Python 版本：3.10 到 3.14，装之前先确认环境
🚀 从零到第一次输出
装。全量包装齐所有格式支持：
pip install "markitdown[all]"
pip install "markitdown[pdf,docx]"
第一行是全量安装；第二行按需装，只覆盖 PDF 和 Word 两种格式。
跑。任何受支持的文件都这样转：
markitdown book.epub -o book.md
不加 -o 时结果直接打印到终端，适合快速预览。
看。打开 book.md，书名、作者、出版社等从 EPUB 的 content.opf 解析出的元数据放在正文前面；转 PDF、Word 时，标题层级、列表、表格都变成对应的 Markdown 结构，不糊成一大段文字。
🧰 场景实战
把 PDF 论文喂进 RAG 管道
文档进大模型问答前，先转成结构化文本。markitdown 支持管道输入，从字节流自动嗅探格式：
cat paper.pdf | markitdown -x pdf
学术论文首页转出来的标题、作者行、正文段落都是结构化文本，可直接分块入库；-x pdf 是给 stdin 的格式提示，省略也能自动识别。它只针对带文字层的数字 PDF，纯扫描页会转出空内容，留给插件部分处理。
表格和幻灯片进检索库
会议纪要、财务报表、幻灯片转完就能全文检索，不用打开 Office：
markitdown finance.xlsx -o finance.md
markitdown deck.pptx -o deck.md
Excel 表格变成 Markdown 管道表格，PPT 按幻灯片切分，原生文本、表格、演讲者备注都保留。注意 .xls 与 .xlsx 依赖不同，没装对应 extras 时该格式直接不可用。
抽取图片元数据，转录音频
图片输出 EXIF 元数据（设备、拍摄时间、坐标）成 Markdown 字段；wav、mp3 转录成文字，先装音频转录依赖：
pip install "markitdown[audio-transcription]"
markitdown meeting.m4a -o meeting.md
YouTube 链接可直接传，抓字幕后转换，需装 [youtube-transcription] 依赖。传入 LLM 客户端时，markitdown 还能给图片顺带生成一句描述；这张图就是项目测试素材里专测该能力的样本。
⚙️ 从单条命令到生产
Python API 调用。写自动化流程时用代码调：
from markitdown import MarkItDown
md = MarkItDown()
print(md.convert("data.xlsx").markdown)
服务端环境建议改用 convert_local()，只处理本地文件；默认入口 convert() 会接受本地文件、远程 URI 和字节流，入口是故意做得宽的。
批量。没有专门的目录模式，套一层循环：
for f in *.pdf; do
markitdown "$f" -o "out/${f%.pdf}.md"
done
插件扩展。先查已装了什么，再用 -p 启用：
markitdown --list-plugins
markitdown document.pdf -p
官方 markitdown-ocr 插件 能给 PDF、Word、PPT、Excel 转换器加 OCR 能力，读出文档里嵌入图片中的文字——扫描件文档就走这条路；没传 llm_client 时 OCR 被静默跳过，回退到内置转换器。要加新格式可参考 sample plugin 模板：实现 accepts() 和 convert() 再注册入口点。
云端端点。复杂表格、扫描 PDF 要更高质量提取时，用 -d 接 Azure Document Intelligence，或 --use-cu 接 Content Understanding，都是付费云 API。
⚠️ 避坑与边界
- 扫描版 PDF：内置转换器只读文字层，纯图片页面转出空内容；加 markitdown-ocr 插件配 LLM 客户端，或接云端端点。
- 像素级排版：输出服务文本分析，不做版式；要还原版面换专业排版工具。
- 不受信任的输入：它按当前进程权限做 I/O，和 open()、requests.get() 一个性质；服务端场景先校验输入，优先调 convert_local() 这类最窄入口。
- 视频文件：内置转换器不支持视频，需走 Azure Content Understanding 端点。
- 可选依赖缺失：没装 [xlsx] 等 extras 时该格式不可用，报的是转换失败，别误以为是文件坏了。
一句话判断：它服务"文字进管道"的场景，不服务"页面要好看"的场景。
📋 速览
| 参数 | 一句话作用 |
|---|---|
-o | 写输出文件，不加则打印终端 |
-x | 提示文件扩展名（stdin 有用） |
-m / -c | 提示 MIME 类型 / 文件编码 |
-p | 启用第三方插件 |
--list-plugins | 列出已安装插件 |
-d | 改用 Document Intelligence 提取 |
--use-cu | 改用 Content Understanding 提取 |
--keep-data-uris | 输出保留 base64 内嵌图片 |
| 维度 | markitdown | 在线转换工具 | 手动复制粘贴 |
|---|---|---|---|
| 处理位置 | 完全本地 | 上传第三方服务器 | 本地 |
| 输出目标 | 结构化文本喂 LLM | 可读页面 | 零散文本 |
| 结构保留 | 标题、表格、列表 | 基础格式 | 容易断裂 |
| 元数据 | EPUB 等自动带出 | 大多丢失 | 没有 |
| 依赖 | Python 3.10–3.14 | 浏览器 + 网络 | 无 |
本地、离线、结构化 Markdown 进大模型，选 markitdown，装 [all] 覆盖绝大多数场景。要还原版式换专业排版工具；扫描件加 OCR 插件，别硬扛。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
