MarkItDown 文档转 Markdown 实战：30 多种格式一个命令搞定

MarkItDown 文档转 Markdown 实战：30 多种格式一个命令搞定

【免费下载链接】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 做检索、分析或入库。它同时提供命令行和 Python API 两种用法，还内置了多模态 LLM 能力——给图片生成描述、对扫描件做 OCR。适合需要批量处理文档、给 RAG 准备语料，或者想给 LLM 流水线加一个"文档入口"的同学。

先看看它能接住哪些活

• 扫描件和发票 PDF 没有文本层，传统提取器只能拿到空白；MarkItDown 的 OCR 插件可以调用视觉模型把整页图里的文字读出来。
• 手上有一堆.docx、.xlsx、.pptx，想统一变成纯文本语料，逐文件格式写解析代码太累——它按文件内容自动选择转换器，你只管扔文件。
• 图片文件直接丢进去，装上 LLM 客户端后它能输出图片的文字描述，而不只是 EXIF 元数据。

环境准备：两行装完，五分钟跑通

官方包在 PyPI 上，装全量功能集最简单：

pip install markitdown[all]

[all]会带上 PDF、PPTX、DOCX、XLSX 等格式的解析依赖。如果只需要其中几类，可以按需安装，例如pip install "markitdown[pdf,docx]"。要求 Python 3.10+。

如果要从源码安装并看实现：

git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[all]

验证是否装好，打开终端运行markitdown --version，能打印版本号就可以开始用了。

功能一：命令行单文件转换

是什么：安装后你会得到一个markitdown命令，把文件路径给它，Markdown 输出到终端。

怎么跑起来：

markitdown example.pdf -o example.md

也可以直接重定向：markitdown example.pdf > example.md。文件类型不用你指定，它靠文件内容嗅探（magika）来判断。从管道读入时用-x给个扩展名提示：

cat data.bin | markitdown -x pdf

效果/注意点：输出里表格会变成 Markdown 表格，HTML 来源会走 Markdown 化流程。想省事就一条命令；遇到识别不了的格式，看下一节的排错清单。

功能二：Python API 批量转换

是什么：在代码里实例化MarkItDown对象，调convert方法，返回值直接给你 Markdown 文本。

怎么跑起来：

from markitdown import MarkItDown md = MarkItDown() for f in ["test.docx", "test.xlsx", "test.pdf"]: with open(f + ".md", "w", encoding="utf-8") as out: out.write(md.convert(f).text_content)

效果/注意点：批量转换就是上面这个循环，配合pathlib遍历目录即可。注意返回对象上取文本用text_content，写 Markdown 文件用markdown字段，两者内容一致但后者更直白。

功能三：给图片配个"会写字的眼睛"

是什么：给MarkItDown传入一个 OpenAI 兼容的客户端和模型名，图片转换时会自动调用视觉模型生成一段文字描述，追加在 EXIF 元数据后面。

怎么跑起来：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("photo.jpg").text_content)

跑出来的 Markdown 大致长这样：先几行ImageSize: ...之类的元数据（装了 exiftool 才有），然后一个# Description:标题，下面是模型写的图片描述。注意：不传llm_client时只会输出元数据，不会报错，描述部分直接缺席——这是最常见的"为什么没有描述"问题。

进阶：OCR 插件与转换器优先级

MarkItDown 的扩展机制是插件：第三方包通过markitdown.plugin入口点注册自己的转换器，比如官方的 OCR 插件会给 PDF/DOCX/PPTX/XLSX 装上"文档内嵌图片 OCR"和"整页扫描件 OCR"能力。启用方式是打开插件开关并照常传 LLM 参数：

md = MarkItDown( enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o", llm_prompt="Extract all text, preserving table structure.", ) result = md.convert("scanned_invoice.pdf")

OCR 转换器注册在更高优先级（-1.0，先于内置的 0.0）上，所以同一份文件它会抢先处理；单次 LLM 调用失败不会中断，对应图片的文本缺失但转换继续。没有可提取文本的扫描页会被自动识别，整页按 300 DPI 渲染后送给视觉模型。核心实现在 _ocr_service.py，插件如何接入可以看 markitdown-ocr 包。

避坑清单

• 现象：pip install markitdown后转 PDF/PPTX 报不支持。原因：没装可选依赖，核心包只含文本/HTML 类解析。处理：改用pip install markitdown[all]，或只装需要的特性如[pdf]、[docx]。

• 现象：装了 OCR 插件，输出里却没有图片文字。原因：没传llm_client/llm_model，插件会静默跳过 OCR 回退到普通转换器。处理：确认两个参数都传了；再检查 API key 和网络，模型名是否有效。

• 现象：转图片只有几行元数据，没有描述。原因：同上，LLM 客户端缺失；或者系统没装 exiftool（影响元数据部分）。处理：传 LLM 参数；元数据缺失可brew install exiftool或指定exiftool_path。

• 现象：管道输入转换失败或识别错类型。原因：没有文件名，扩展名嗅探不到。处理：加-x pdf、-m text/html之类的提示参数。

• 现象：同一类文件被插件和内置转换器"打架"。原因：插件转换器按优先级覆盖，enable_plugins=False可关掉。处理：需要稳定行为时显式指定开关；内置转换器注册逻辑可参考 converters 目录。

小结

MarkItDown 的价值就一句话：把"一堆格式各异的文件"变成"LLM 能直接读的 Markdown"，命令行三分钟上手，Python API 和插件机制负责把扫描件、图片这类硬骨头啃下来。想深入可以看 markitdown 包的 README 和 converters 源码目录，每类文件怎么被解析、优先级怎么排，源码里一目了然。

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