MarkItDown 实操指南：把 Office 文档转成 Markdown 只要一分钟

MarkItDown 实操指南：把 Office 文档转成 Markdown 只要一分钟

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

MarkItDown 是一个免费开源的 Python 工具，一行命令把 PDF、Word、PPT、Excel、图片、音频转成 Markdown。它解决的是"把杂乱文档喂给 LLM"的问题：标题、列表、表格这些结构都会保留下来，而不是压成一坨纯文本。

转换效果速览

先看仓库里自带的测试 PDF（一篇论文的首页）转出来的结果：

转出的 Markdown 大致长这样，正文段落完整，脚注也保留了：

1 Introduction Large language models (LLMs) are becoming a crucial building block in developing powerful agents that utilize LLMs for reasoning, tool usage, and adapting to new observations ...

环境与获取

要求 Python 3.10 及以上，建议先在虚拟环境里装，避免依赖打架。

• 普通用户，装现成的就行：

pip install 'markitdown[all]'

• 开发者想改源码，先克隆仓库再装开发版：

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

[all]表示装齐所有格式依赖；如果只用 PDF 和 Word，装markitdown[pdf, docx]更省空间。

第一次运行

装完你会多出一个markitdown命令。把路径扔给它，结果直接打印到终端：

$ markitdown packages/markitdown/tests/test_files/test.pdf 1 Introduction Large language models (LLMs) are becoming a crucial building block ...

想存成文件，加-o：

$ markitdown test.pdf -o test.md

也支持管道，方便接进现有脚本：cat test.pdf | markitdown。看到结构化的 Markdown 输出，就说明环境通了。

核心能力拆解

输入：先认文件，再派活

拿到字节流后，MarkItDown 先用魔数（文件头签名）识别真实格式，而不是只看扩展名，然后在一串注册好的转换器里按优先级匹配。每个格式对应一个转换器，通过accepts()判断自己能不能处理：

self.register_converter(PdfConverter()) self.register_converter(DocxConverter()) self.register_converter(PlainTextConverter(), priority=PRIORITY_GENERIC_FILE_FORMAT)

具体格式优先，纯文本兜底。匹配不到就明确报"不支持"，不会硬转。

处理：抽取结构而非纯文本

这是它和"一键转文本"工具的区别：Word 的标题样式变成#，表格变成 Markdown 表格，超链接保留 href；Excel 按工作表输出表格；PPT 每页一张幻灯片逐页转。转出来的东西既给 LLM 读，人看也不算费劲。

输出：图片、音频也能变文字

对图片，它提取 EXIF 元数据（尺寸、标题、作者），如果你配了多模态 LLM，还会生成图片描述；音频则走语音转写。下图就是 LLM 描述功能用的测试图，配上llm_client后它会输出对红圆蓝方块的描述：

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

进阶用法

Docker 跑无环境依赖：不想装 Python 依赖时，仓库根目录的 Dockerfile 可以直接构建镜像，把文件从 stdin 喂进去：

docker build -t markitdown:latest . docker run --rm -i markitdown:latest < report.pdf > output.md

插件机制：第三方转换器默认不加载，markitdown --list-plugins看装了哪些，加-p启用。比较常用的是markitdown-ocr插件，靠 LLM Vision 从 PDF、PPT 里内嵌的图片中提取文字，不用额外装 OCR 库。

常用参数（CLI 和 Python 基本对应）：

两个踩过的坑：从 stdin 读数据时没有任何线索可猜格式，务必带上-x；markitdown-ocr插件没传llm_client时会静默跳过 OCR 走内置转换器，不报任何错，别以为插件没装。

答疑

现象：PDF 转出来是空白或一堆乱码。原因：这是扫描件，页面里没有文字层，离线提取不到。解决：用-d -e <endpoint>接 Azure Document Intelligence，或上markitdown-ocr插件。

现象：cat file | markitdown报错说不支持该格式。原因：管道输入丢掉了文件扩展名，无法确定格式。解决：加-x pdf手动给提示，或直接把文件路径作为参数。

现象：装完markitdown[all]之外，单独装的 markitdown 转 pptx 失败。原因：各格式依赖是可选的，基础包不含它们。解决：按需补装，如pip install 'markitdown[pptx]'。

现象：接了 Azure 端点后部分格式仍走本地转换。原因：云端转换按文件格式路由，只有命中端点支持类型的文件才走云端。解决：确认文件格式在端点支持范围内，或调整docintel_file_types路由范围。

收尾

去终端跑一条markitdown 你的文件.pdf | head -20验证安装，然后挑一份真实文档转一遍。某个具体格式转换效果不对，直接去仓库 Issues 贴复现文件反馈。

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