MarkItDown 使用指南：一条命令将 10 余种办公文档转为 Markdown

MarkItDown 使用指南：一条命令将 10 余种办公文档转为 Markdown

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

把一沓 PDF 论文、Word 报告和 Excel 报表喂给大模型之前，通常要先手动导出文本，标题、表格、列表这些结构基本都会丢。MarkItDown 是微软 AutoGen 团队开发的 Python 工具，把这些文件直接转成保留结构的 Markdown，命令行或 Python API 均可调用。项目要求 Python 3.10 以上，输出面向文本分析和 LLM 消费，而非高保真的人类阅读排版。

MarkItDown 支持哪些文档格式

内置转换器覆盖办公文档与网页类格式，多格式依赖通过 extras 按需安装：

输入类型	转换行为
PDF	提取正文，保留标题与表格结构
Word / PPT / Excel（docx、pptx、xlsx、xls）	解析文档对象，输出对应 Markdown 结构
图片	读取 EXIF 元数据，可接 LLM 生成图片描述
音频（wav、mp3 等）	元数据 + 语音转文字（需 audio-transcription 依赖）
HTML / CSV / JSON / XML	转为表格、列表等 Markdown 表示
ZIP / EPub	遍历包内文件逐个转换
YouTube 链接	抓取视频字幕文本

MarkItDown 安装命令

建议先建虚拟环境，再用 pip 安装完整功能：

pip install 'markitdown[all]'

也可以从源码安装：

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

一行命令把文件转成 Markdown

命令行是最短路径：

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

也可以用管道，方便接进脚本：

cat path-to-file.pdf | markitdown

输出的 Markdown 用轻量标记表达标题、表格和链接，token 开销较低，适合直接拼进 LLM 上下文。环境只需要少数格式时，按 extras 精简安装能少装很多依赖：

pip install 'markitdown[pdf, docx, pptx]'

容器场景可用仓库根目录的 Dockerfile 构建镜像：

docker run --rm -i markitdown:latest < report.pdf > out.md

在 Python 代码中集成 MarkItDown

from markitdown import MarkItDown md = MarkItDown() result = md.convert("test.xlsx") print(result.text_content)

核心实现在 packages/markitdown/ 下，每种格式对应converters/目录里的一个模块。官方还提醒：在不可信环境中应校验输入，并优先调用convert_local()、convert_stream()这类最窄的转换接口，而不是泛用的convert()。

进阶：LLM 图片描述与云增强转换

传入llm_client后，图片与 PPT 内嵌图片会由 LLM 自动生成文字描述，上图是仓库测试用例中用来验证这一能力的样例图：

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

markitdown-ocr 插件把同一套 LLM 视觉能力扩展到 PDF、DOCX、PPTX、XLSX 的嵌入图片，不引入新的 ML 二进制依赖，源码见 packages/markitdown-ocr/。

需要更高提取质量时可接入 Azure：Document Intelligence 在命令行加-d -e <endpoint>启用；Content Understanding 额外支持音频和视频，还能把发票金额、日期等字段以 YAML front matter 形式输出在 Markdown 头部，适合做结构化字段抽取。

插件生态与社区贡献

插件默认关闭，用markitdown --list-plugins查看已安装项，--use-plugins启用转换；仓库还内置了 MCP 服务包 packages/markitdown-mcp，插件开发可参考 packages/markitdown-sample-plugin/ 示例，社区插件可在 GitHub 搜索 #markitdown-plugin 标签查找。贡献走 issue 和 PR，标注 open for contribution 的条目适合新手入手，本地开发在 packages/markitdown 下用hatch test跑测试即可。

回到开头那沓 PDF：跑一遍 MarkItDown，得到的就是保留标题和表格结构的 Markdown 文件，可以直接进检索库或 LLM 上下文。工具本身很薄，复杂版式的提取质量仍取决于具体文档，扫描件建议配合 OCR 插件或云增强转换使用。

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