企业官网建设流程全解析

markitdown 实战指南：一条命令把 PDF、Word、EPUB 转成 Markdown

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

markitdown 是微软开源的 Python 文档转 Markdown 转换工具。它把 PDF、Word、PPT、Excel、EPUB、图片、音频一行命令转成保留结构的 Markdown。照这篇走完，你能独立完成安装、跑通第一条转换、写出批量脚本。

什么场景选 markitdown

适合：

• 文档要喂给大模型、搭知识库
• 文件不能离开本地，转换必须离线
• 批量处理一批 Office 文件
• 提取 EPUB 书目信息、图片 EXIF 等元数据

不适合：

• 像素级排版还原：输出服务文本分析，不是给你二次出版
• 扫描版 PDF：内置转换器只读文字层
• 视频文件：内置没有视频转换器

markitdown 安装：全量 [all] 与按需依赖

要求 Python 3.10 到 3.14，装之前先确认版本。一条命令装齐全部格式：

pip install "markitdown[all]" # 全部格式 # 或按需安装，例如只要 PDF 和 Word pip install "markitdown[pdf,docx]"

第一行装好 markitdown 命令行工具和 Python 包，所有格式开箱即用；第二行只装两个格式的依赖，环境更轻。想从源码跑：git clone https://gitcode.com/GitHub_Trending/ma/markitdown后执行pip install -e "packages/markitdown[all]"。

第一条转换：把 book.epub 变成 Markdown

markitdown book.epub -o book.md

这条命令读文件、按格式选转换器，把结果写进 book.md。不加-o时结果直接打印到终端，适合快速预览。

打开 book.md，你会看到正文顶部多了几行加粗字段：markitdown 解析了 EPUB 里的 content.opf，把书名、作者、出版社等元数据自动带出来放在正文前。这个意外收获让你不用手工补书目信息。

场景一：把文档喂给大模型

要达成的效果：一批论文、合同变成干净的Structured 文本，直接进模型。

cat example.pdf | markitdown

这条命令从标准输入读字节流，自动嗅探格式并打印结构化结果。嗅探不准时手动提示：-x给扩展名，-m给 MIME 类型，-c给编码。

上图是仓库测试素材里的一页论文。转换后标题、作者行、正文段落都会变成结构化文本，可以直接喂模型。注意它针对的是带文字层的数字 PDF，纯扫描件见文末边界清单。

场景二：表格与幻灯片变成可检索文本

要达成的效果：会议纪要、财务报表、课件批量进全文检索，不用打开 Office。

命令不变，换文件名即可，例如markitdown report.docx -o report.md：Excel 表格自动变成 Markdown 表格，PPT 按幻灯片切分，Word 保留标题层级，文档里的公式转成 LaTeX 写法。转完即可直接全文检索。

场景三：图片元数据与音频转录

要达成的效果：非文档资产里的信息也不丢。

图片会提取 EXIF 元数据（设备、拍摄时间、坐标）输出成 Markdown 字段；wav、mp3 可以转录成文字，需装[audio-transcription]；YouTube 链接能直接传，抓字幕后转换，需装[youtube-transcription]。

这种测试图，传入 LLM 客户端后 markitdown 还能顺带生成一句图片描述。这张图就是仓库里专门测这个能力的样本。

markitdown Python API 与批量转换

写自动化流程用代码调，核心就三行：

from markitdown import MarkItDown md = MarkItDown() print(md.convert_local("data.xlsx").markdown)

服务端环境优先用convert_local()，它只处理本地文件。默认入口convert()还会接受远程 URI 和字节流，入口是故意做得宽的。

批量转换没有专门的目录模式，套一层循环即可：

for f in *.pdf; do markitdown "$f" -o "out/${f%.pdf}.md" done

它逐个转当前目录下的 PDF，同名 .md 落到 out/ 里。

插件：用 -p 扩展 markitdown

先看装了什么，再用-p启用：

markitdown --list-plugins markitdown document.pdf -p

官方 OCR 插件 给 PDF、Word、PPT、Excel 转换器加 OCR 能力，配合 LLM 客户端读出文档里嵌入图片中的文字，扫描件走这条路。没传 llm_client 时 OCR 会被静默跳过，回退到内置转换器，不会报错。要开发新格式，照 样例插件模板 实现accepts()和convert()两个方法再注册入口点。

复杂表格、扫描 PDF 要更高提取质量时，用-d接 Azure Document Intelligence，或--use-cu接 Azure Content Understanding。两者都是付费云 API，内置转换器才是默认免费本地路径。

⚠️ 参数速查与失败边界

边界都按"遇到 X，改走 Y"处理：

• 遇到纯扫描 PDF（无文字层）转出空内容 → 改走 OCR 插件加 LLM 客户端，或-d接云端提取
• 需要像素级排版 → 别硬扛 markitdown，改走专业排版工具
• 输入可能来自不受信任用户 → 先校验文件路径与网络目标，改走convert_local()，别直接喂convert()
• 遇到视频文件 → 内置不支持，改走--use-cu接 Azure Content Understanding
• 某格式报转换失败 → 多半是缺可选依赖，如 Excel 要装[xlsx]，补上对应 extras 再试

本地、离线、要结构化 Markdown 进大模型——选 markitdown，装[all]覆盖绝大多数场景； 要还原版式——换专业排版工具，别指望它； 有扫描件或视频——加 OCR 插件或云端端点再转； 只是偶尔翻几个文件且内容不敏感——在线工具也行，不必上全套。

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