MarkItDown 怎么用：万能格式转换

文档格式这座孤岛

你手里有一份 PDF 合同、一个 PPTX 路演稿、一张截图，还有一段会议录音。老板要你把它们整理成一份可以全文检索的资料。传统做法是开四个软件、复制粘贴、再手工调格式——半天就没了。

MarkItDown 解决的就是这个麻烦：把各种文件和办公文档统一转成 Markdown。它支持 PDF、DOCX、PPTX、XLSX、图像（带 OCR）、音频（带转录）、HTML、CSV、JSON、XML、ZIP、YouTube URL、EPub 等格式，来自 claude-scientific-skills 系列（MIT 许可），兼容 Claude Code、OpenClaw、Hermes Agent 等工具。

为什么偏偏是 Markdown？因为它是纯文本、带结构、人和 AI 都读得懂。一旦所有资料都归一到这个格式，后面的检索、摘要、喂给大模型，全都顺理成章。

安装

它是标准的 Python 包，一条命令：

pip install markitdown

装好后有两条使用路径：在自己的脚本里当库调用，或者在兼容的 AI 工具中启用对应 Skill，让 agent 在对话过程中顺手完成转换——比如你说"把这份 PDF 的核心内容整理出来"，它会先转 Markdown 再提炼。两条路径不冲突，批处理走脚本，零散的临时转换交给对话更省事。

第一次转换

最小用法只有三行代码。创建实例，调用 convert，拿走 text_content：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

想把结果存成文件，就把 result.text_content 写进 .md 即可。第一次建议拿一份结构简单的 PDF 试手，确认环境里依赖齐全、输出符合预期，再碰那些排版复杂的材料。

常见格式的实操套路

不同格式的入口是同一个 convert，差异只在输出内容上：

Office 文档：DOCX、PPTX、XLSX 转出来是带标题层级和表格的 Markdown，适合直接进入知识库
图像：转换时走 OCR，输出图片里提取到的文字；配合多模态能力时还可以生成图像描述
音频：转换即转录，会议录音变成可检索的文字稿
网页与 YouTube URL：直接把 URL 传给 convert，网页正文变成干净的 Markdown；YouTube 链接则提取字幕文本
数据文件：CSV 转成 Markdown 表格，JSON、XML 转成结构化文本，方便喂给后续的 LLM 流程
压缩包与电子书：ZIP 会处理包内内容，EPub 电子书也能整本转成文本

批量处理一个目录的 PDF 也不复杂——os.listdir 遍历，逐个 convert，输出到同名 .md 文件，条目详细说明里就给了这样的完整示例。真正花时间的往往不是写代码，而是转换后的抽查：挑几份版式最复杂的文件，确认表格和标题层级没有错位。

哪些场景最划算

知识库清洗：把历史积累的 Word、PPT、PDF 批量转成 Markdown，统一进检索或 RAG 管线，这是它最经典的主场
内容提取：从 PDF 报告里抽文字做二次分析，省去复制粘贴和格式修复
自动化工作流：作为文档处理流水线的第一道工序，后面接摘要、翻译、入库都很顺
多模态资料归档：截图 OCR、录音转写、网页抓取，一个入口全收，归档格式从此统一

反过来说，如果你的日常只是偶尔转一两个文件，打开在线转换网站可能更快——这个工具的价值在"批量"和"可编程"上才体现出来。

局限与替代思路

转换质量取决于原文件结构：排版复杂的 PDF（多栏、嵌套表格）转出来的 Markdown 可能需要人工顺一遍；OCR 对手写体和低清晰度图像的识别率有限；音频转录的时长和语种支持受底层能力约束。它的定位是"格式归一化的第一步"，不是排版还原工具。

如果你的需求是高保真还原文档版式，应该找专门的版面分析方案；如果目标是让内容进入文本工作流，MarkItDown 是轻量且够用的一站。把预期放对，它就是那种装一次、用三年的工具。