MarkItDown 工具实战：一条命令把 PDF 和办公文档转成 Markdown

MarkItDown 工具实战：一条命令把 PDF 和办公文档转成 Markdown

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

markitdown 是一个 Python 命令行工具，把 PDF、Word、Excel、PPT、EPUB 等文件转成纯 Markdown 文本。给大模型喂资料、做文档归档、搭知识管线的人都能直接用。

🎯 谁会被它帮上忙

• 给 LLM 喂资料的人：手上有一堆 PDF 论文、Word 合同要送进大模型分析，手工复制粘贴到提示词里又慢又容易丢格式，转成干净 Markdown 就能直接进 prompt，转完还能 diff 检查内容有没有被改坏。
• 做文档管理的工程师：仓库里 docx、xlsx、epub 混着存，想统一成 Markdown 进 Git 做版本追踪，手动一个个转不现实；而且转换全程离线，内部文档不用传出去。
• 整理内容的人：想把博客、RSS 里的正文抽出来归档，不想带一堆 HTML 标签和脚本代码；手头的 mp3、m4a 录音也能顺带转成文字稿。

⚡ 30 秒装好

一条命令搞定，前提是你的 Python 版本在 3.10 及以上：

pip install markitdown[all]

[all] 会装上全部格式依赖。只转 PDF 也可以按需装 markitdown[pdf]，省磁盘。不走 PyPI 的话，clone 源码后执行pip install -e packages/markitdown[all]（https://gitcode.com/GitHub_Trending/ma/markitdown）也一样。

🔧 最小可用命令

markitdown report.pdf -o report.md

跑完生成一份带标题层级、列表和表格的 .md 文件；EPUB 这类带元数据的格式，标题、作者、出版方会作为字段写在文档开头。文件名可以省略，此时从标准输入读取，适合接在管道里用。

🧩 它底层在做什么

流程像印刷厂的车间：文件送进去，分诊、拆版、出清样，三步走完。

1. 分诊：先按扩展名和内容特征（magika 嗅探）判断文件类型，派给对应的转换器。目前内置 20 多种格式，包括 PDF、Word、Excel、PPT、EPUB、HTML、RSS、网页、Jupyter Notebook、Outlook 邮件，还有音频转写。
2. 拆版：每种格式走自己的解析器。以 EPUB 为例，先解开 ZIP 包、读 content.opf 拿到章节目录，再逐章把 XHTML 解析成文本；PDF 则由 pdfplumber 抽正文和表格。
3. 出样：统一输出带 # 标题、列表、表格的 Markdown，元数据放在头部，可直接喂给搜索引擎或大模型。

🚀 三个进阶用法

1. 批量转换：一条 for 循环把目录下所有 PDF 转成同名 .md，直接接在 CI 里跑：

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

2. 管道转换：文件从 stdin 进来没有扩展名时，用 -x 提示格式，避免猜错类型：cat page.html | markitdown -x html -o page.md
3. 查看插件：RTF 等格式靠第三方插件支持，先列出来再决定启用：markitdown --list-plugins

⚠️ 容易踩的坑

• 现象：转 PDF 时报缺少依赖。原因：只装了基础包 markitdown，格式依赖没带进来。怎么办：改装 markitdown[all]，或按格式装对应 extras，如 markitdown[pdf]。
• 现象：从管道输入时转换失败。原因：没有扩展名，工具猜不出文件类型。怎么办：加 -x 扩展名或 -m MIME 类型提示。
• 现象：EPUB 转完没有图片。原因：转换器只提取正文和元数据，不导出包内图片文件。怎么办：需要图片就另外从 epub 包（本质是 ZIP）里解压。
• 现象：网页里的 base64 内嵌图在输出里被截断。原因：默认会截断 data URI 防止输出过大。怎么办：加 --keep-data-uris 保留完整内容。

和替代方案怎么选

结论：要进自动化流水线、数据又不想出本机，选 markitdown；只是偶尔转一两个文件，在线工具也够用。

装好后在终端直接敲 markitdown 能看到完整帮助和各格式参数；要支持新格式，对照 pyproject.toml 里的可选依赖组补装 extras 即可。

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