MarkItDown：3 步把 PDF 和 Office 文档转成 Markdown，让 LLM 一条命令读懂文件-开发者社区

MarkItDown：3 步把 PDF 和 Office 文档转成 Markdown，让 LLM 一条命令读懂文件

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

它能做什么

MarkItDown 是一个轻量级 Python 工具，把 PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV/JSON/XML、EPUB、ZIP 等文件统一转换成 Markdown。它转换时会尽量保留文档结构——标题、列表、表格、链接都以 Markdown 形式保留下来，而不是压成一段乱序纯文本。

它的定位很明确：转换结果主要喂给 LLM 和文本分析管线。主流大模型对 Markdown 的兼容性很好，而且 Markdown 的 token 开销低，适合做文档问答、RAG 索引、批量文本分析。如果你的需求是给人排版看的"高保真还原"，它不是最佳选择。

3 条命令跑起来

需要 Python 3.10 及以上版本，建议先在虚拟环境里操作。

普通用户（安装即用）：

pip install 'markitdown[all]' markitdown --version

开发者（从源码安装）：

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

[all]会装齐所有格式的可选依赖。如果只转换少数几种文件，也可以按需装 extras，例如pip install 'markitdown[pdf, docx, pptx]'，装出来的环境更干净。

一条命令转换 PDF 到 Markdown

把文件放到本地，然后：

markitdown path-to-file.pdf -o document.md

转换结果直接写入 document.md。不想指定输出文件时，用重定向markitdown path-to-file.pdf > document.md也可以；没有实体文件时还支持管道：cat path-to-file.pdf | markitdown。

图片和音频同样可以直接传入，默认会提取 EXIF 元数据。如果希望图片"被看懂"，在 Python API 里传入llm_client和llm_model，转换时会生成图片的文本描述：

md = MarkItDown(llm_client=client, llm_model="gpt-4o") result = md.convert("example.jpg")

仓库测试目录里就有这类样例图，转换后会变成可被模型理解的纯文本：

值得调的几个参数

--use-docintel+-e <endpoint>：改用 Azure Document Intelligence 云端提取，对扫描件、复杂表格效果明显更好；默认不需要，有 Azure 资源且本地转换质量不佳时再开。
--keep-data-uris：输出中默认会截断 base64 数据 URI（内嵌图片），想要保留就加这个开关；默认关闭即可，能省不少体积。
-x/--extension：给无扩展名的输入流提供格式提示，走管道或 stdin 转换时建议补上。
-p/--use-plugins：启用第三方插件，比如 markitdown-ocr，可以对 PDF、DOCX 里的内嵌图片做 OCR。默认关闭，装完用markitdown --list-plugins确认已安装。
llm_client/llm_model（Python API）：为图片和 PPT 内嵌图生成描述。建议只在确实需要时传入，避免每次转换都产生 API 调用。

用 Docker 部署

不想在本地装 Python 环境时，仓库根目录自带 Dockerfile：

docker build -t markitdown:latest . docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

镜像内置 ffmpeg 和 exiftool，音频和图片元数据都能正常提取。容器里就是"进一个文件、出一个 Markdown"的单纯命令，没有插件体系和配置文件，比本地安装更简单，但云端提取等高级用法需要在宿主机侧处理。

4 个容易踩的坑

转换时报错或提示格式不支持：原因是安装时没装对应格式的依赖。解法：改用markitdown[all]，或单独补[pdf]、[docx]等 extras。
扫描版 PDF 转出来是空内容或乱码：原因是离线提取器认不了纯图片页面。解法：换 Document Intelligence（-d -e "<endpoint>"），或装 markitdown-ocr 插件走 LLM 识别，两者都需要云端端点或模型。
终端里打印输出乱码：原因是 stdout 编码吃不下部分字符。解法：改用-o直接写文件，文件写入走 UTF-8 更稳。
在线服务里直接处理用户上传的文件：MarkItDown 以当前进程权限做 I/O，和open()一样，输入被控制就可能被利用。解法：先校验输入，只调用最窄的convert_local()或convert_stream()，不要让用户直接控制文件路径和 URI。

另外提醒一句：只转换和保存你有权限使用的内容。