企业官网建设流程全解析

一条命令把 PDF、Word、Excel 全变成 Markdown？MarkItDown 完整上手指南

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

MarkItDown 是一个轻量级 Python 工具，能把 PDF、Word、Excel、PPT、图片、音频等几十种文件，一条命令转成 Markdown。如果你需要把文档批量喂给大模型、做全文检索或文本分析，它能帮你省掉为每种格式单独写解析器的麻烦。

为什么要把文档变成 Markdown 再喂给 LLM

想象一下这个场景：你手里有几十份 PDF 合同、十几张 Excel 报价单、一摞 Word 会议纪要，想让大模型帮你总结。直接把二进制文件丢进去是不行的——LLM 只认文本。

这时候 Markdown 的价值就出来了。它接近纯文本，没有花哨格式，却保留了标题、列表、表格、链接这些结构信息，而且对大模型来说非常"省 token"。你可以把它理解成"LLM 最友好的中间格式"。MarkItDown 做的就是这件脏活：从各种原始格式里把内容抽出来，按 Markdown 的结构重新组织好，直接可喂给 GPT、Claude 等模型。

它的输出是面向文本分析工具的，所以偶尔不如"排版软件"那样美观，但标题层级、表格结构基本都在，够你做了。

30秒上手：安装 MarkItDown 并跑通第一次转换

先装包，[all]参数会装上所有格式的依赖：

pip install 'markitdown[all]'

装完立刻试一条命令，把任意 PDF 转成 Markdown：

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

怎么判断成功了？打开document.md，如果看到的是# 标题这样的 Markdown 标记、还有保留下来的表格和列表，而不是乱码，就成了。

如果你习惯从源码安装，clone 下来装到packages/markitdown目录即可：

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

实战演示：三个最典型的用法

一条命令转换 PDF，并指定输出文件

想干嘛：把手头的 PDF 变成.md文件，不想手动重定向。

怎么跑：用-o参数直接指定输出文件，比>更直观：

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

得到什么：一个结构完整的 Markdown 文件，大致长这样：

# REPAIR-2022-INV-001 ## Customer Information Acme Plumbing Co. ## Line Items | Description | Qty | Amount | | ------------------ | --- | -------- | | Valve replacement | 1 | 180.00 | | Labor | 2 | 140.00 |

标题、表格、键值对都被还原成了 Markdown 结构，后续无论是给 LLM 还是做检索都能直接用。

Python API 转换 Excel 表格

想干嘛：把 Excel 报价单转成 Markdown 表格，嵌进自己的流程里。

怎么跑：三行代码搞定：

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

得到什么：终端里直接打印出 Markdown 表格：

| 产品 | 数量 | 单价 | | ------ | ---- | ------- | | 咖啡豆 | 2 | 64.00 |

result.text_content拿到的就是完整 Markdown 字符串，你可以再加工，比如直接拼进 prompt。

让 LLM 描述图片，自动写进 Markdown

想干嘛：文档里有插图，希望 LLM 顺便把图片内容"说"出来。

怎么跑：传入一个 OpenAI 兼容的llm_client和模型名即可：

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

得到什么：图片对应的 Markdown 里会多出一段 LLM 生成的描述，比如"图中有一个红色圆形和一个蓝色正方形……"。不配llm_client时它也能提取 EXIF 元数据（拍摄时间、尺寸等），只是没有描述文字。

进阶技巧：新手最常踩的三个坑

坑一：报"格式不支持"，多半是没装对应依赖。markitdown基础包不带全部格式支持，想只装需要的，可以按格式选装，更省空间：

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

坑二：插件默认是关闭的。如果你装了第三方插件（比如 OCR 插件），记得显式开启，命令行加--use-plugins，API 里写MarkItDown(enable_plugins=True)。

坑三：别把不可信的文件直接丢给它。MarkItDown 会以当前进程的权限读写文件和网络资源。处理来源不明的文件时，建议先用convert_local()、convert_stream()这类最小范围的接口，而不是对任意 URL 直接convert()。

另外记住一个环境要求：Python 3.10 以上，低于这个版本装不上。

还能延伸到哪里

官方仓库里还有一系列可以按需叠加的能力：markitdown-ocr插件能给 PDF、Word、PPT 里嵌入的图片做 OCR；音频文件支持语音转录，YouTube 链接可以抓取字幕；追求更高质量时还可以接 Azure Document Intelligence 走云端解析。用到哪步装哪步，不用一次全上。

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