MarkItDown 完整上手指南：一条命令，10 余种格式转成 Markdown

MarkItDown 完整上手指南：一条命令，10 余种格式转成 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 和文本分析管道直接消费。

一份三页的 PDF 维修账单，过去要手动截图、誊数字；现在跑一条命令，几十秒后你拿到的是一份带表格的 Markdown，客户信息、工时、税率、总计各归其位。这就是 MarkItDown 做的事：把格式五花八门的输入，压成模型直接能读的一种输出。

📋 MarkItDown 能力速览：支持哪些输入格式

每种格式背后是独立的转换器，convert()会结合文件内容自动识别类型并路由，不用你手动指定格式。

🚀 MarkItDown 安装教程：一条命令出结果

pip install 'markitdown[all]' markitdown report.pdf -o report.md

要求 Python 3.10+。[all]装全部可选依赖；只用部分格式时按组安装更轻，比如pip install 'markitdown[pdf,docx,pptx]'。

Python API 同样三行内搞定：实例化MarkItDown()，调用convert("test.xlsx")，从返回结果的.text_content取 Markdown。另外支持管道输入cat a.pdf | markitdown，仓库根目录的 Dockerfile 可以直接构建镜像跑docker run。

🧩 功能精选：3 个值得知道的设计

结构优先，但不做像素还原。内置转换器统一以保留结构为目标：Word 的标题层级、Excel 的行列、PDF 的表格，都映射到对应 Markdown 语法，而不是压成一坨纯文本。README 里也明说了它的定位——输出主要服务于文本分析工具，若要高保真排版还原，转完建议人工校对一遍。

自动识别 + 插件注册机制。格式识别不靠扩展名硬猜，底层用魔数检测判断文件内容；第三方转换器通过 entry point 挂进来，markitdown --list-plugins列出已装插件，加-p参数启用。想自己写转换器，仓库里的 packages/markitdown-sample-plugin 就是一个最小样例，照抄结构即可。

LLM 图像描述与 OCR 走同一条通道。给MarkItDown传入llm_client和llm_model，图片文件会附带 LLM 生成的文字描述；装上 markitdown-ocr 插件后，PDF、DOCX、PPTX、XLSX 里嵌入的图片也能走同一套 LLM Vision 做 OCR，不用额外引入 OCR 库。

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("with_images.pdf").text_content)

🧾 实战：多页 PDF 账单转成带表格的 Markdown

仓库测试目录里躺着一份多页维修账单样例（packages/markitdown/tests/test_files/REPAIR-2022-INV-001_multipage.pdf），直接拿它试：

markitdown REPAIR-2022-INV-001_multipage.pdf -o estimate.md

输出里有两张 Markdown 表格：一张并排放客户保单信息和车辆信息（VIN、里程、车型），另一张是费用明细——零件 2100、两项工时合计 525、材料费 90，再到 10.20% 的税和 GRAND TOTAL 5,738。数字一个不少，且能被脚本直接解析做对账。

论文类 PDF 同理，上面这种标题、作者行、图表、脚注齐全的学术页，转出来是层级标题加图片占位加正文，参考文献和脚注也不会丢。

⚠️ 避坑指南：扫描版 PDF、编码与安全

• 扫描版 PDF 转出来是空的。内置 PDF 转换依赖文本层，纯图片扫描件没有可选文字，要么上 markitdown-ocr 配 LLM 客户端，要么走 Azure Content Understanding（CLI 加--use-cu）用云端 OCR。
• 乱码先查编码。输出统一按 UTF-8 写文件，终端显示异常时先用-o落盘再用编辑器打开；源文本文件非 UTF-8 编码的，用--charset给个提示。
• 服务器场景别裸用 convert()。它接受本地文件也接受远程 URL，且以当前进程权限执行 I/O。对外服务建议改用更窄的convert_local()，并在调用前校验输入。

结尾

MarkItDown 把"多格式文档喂给 LLM"这一步收敛成了一条命令：装好、转换、校对，十分钟能跑通第一个文件。

下一步：执行pip install 'markitdown[all]'，把你手头任意一份 Office 文档或 PDF 转成 Markdown，重点检查表格保留得如何。需要源码的话：git clone https://gitcode.com/GitHub_Trending/ma/markitdown，然后pip install -e 'packages/markitdown[all]'即可本地开发。

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