企业官网建设流程全解析

markitdown 完全指南：PDF、Word、Excel 一键转 Markdown 的 3 条路径

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

markitdown 是微软开源的 Python 工具，能把 PDF、Word、PPT、Excel、EPUB 等文件转成带结构的 Markdown，默认全程离线。如果你的文档要喂给大模型、建知识库，或要批量整理 Office 文件，最短路径是：装好markitdown[all]，跑一条命令，拿到保留标题、表格、列表的 Markdown 文本。

它解决什么问题

大模型问答和 RAG 知识库的入口几乎都是文本，而手头的资料大多是二进制文档。直接复制粘贴进去，标题层级没了、表格糊成一团、token 还花得多——markitdown 就是补这一环：把 PDF、Word、HTML、CSV 这类文件转成 LLM 原生"会说"的 Markdown，结构保留、token 消耗也低。

批量整理场景同样典型。几百份 Word 合同、Excel 报表，逐份打开再粘贴不现实，markitdown 提供命令行入口，一条命令一个文件，循环一跑就全部变成可全文检索的纯文本，不用再依赖 Office 软件打开。

第三个场景是合规约束：文件不能出本地。在线转换工具意味着上传到第三方服务器，而 markitdown 的内置转换器完全在本地进程里跑，不经过任何服务器，装好即可离线使用。

第一次上手

先确认 Python 版本在 3.10 到 3.14 之间，官方建议用虚拟环境避免依赖冲突。然后一条命令装齐所有格式支持：

pip install 'markitdown[all]'

装完你会得到markitdown命令行工具。挑手边任意一个受支持的文件试试，比如一本 EPUB：

markitdown book.epub -o book.md

它读文件、按格式自动选转换器，把结果写进book.md；不加-o时结果直接打印到终端，适合先预览一眼。

打开book.md看效果：EPUB 会解析content.opf，在正文前自动带上Title:、Authors:、Publisher:等加粗元数据字段；PDF、Word 的标题、列表、表格则变成对应的 Markdown 结构，而不是一整段糊在一起的文本。这就是它和"纯文本提取"的区别——输出是给文本分析工具消费的，结构在，检索和问答才有抓手。

三条转换路径，按需选

markitdown 的提取能力分三层，从免费到付费依次升级，按需求叠加即可。

本地内置转换器：免费离线的默认路径

不装任何额外端点，markitdown命令走的就是这条路。PDF、Word、PowerPoint、Excel（含旧版.xls）、HTML、CSV/JSON/XML、EPUB、ZIP 都能转；图片提取 EXIF 元数据，wav/mp3 装[audio-transcription]依赖后可转语音文字，YouTube 链接装[youtube-transcription]依赖后抓字幕转换。代价只有一点：内置转换器读的是数字文件的文字层，扫描版 PDF 的页面上只有图片、没有文字层，转出来是空的——这种情况留给后两条路径。

上面这张图就是项目测试素材里的一篇学术论文 PDF 首页，这种带文字层的数字 PDF 是内置转换器的标准输入。

插件扩展：装个依赖，让图片里的字也进 Markdown

官方插件markitdown-ocr给 PDF、Word、PPT、Excel 的转换器加 OCR 能力：用 LLM 视觉模型读出文档里嵌入图片中的文字，复用 markitdown 已有的llm_client/llm_model机制，不引入新的机器学习库。装法是pip install markitdown-ocr，转换时传一个llm_client即可；命令行为markitdown --list-plugins看已装插件、加-p参数启用。没传llm_client时 OCR 会被静默跳过，回退到内置转换器，不会报错。

除了 OCR，传入llm_client后 markitdown 还能给 PPT 和图片文件顺带生成一句图片描述，上面这张红圆蓝方的测试图就是项目里专门验证这个能力的样本。

新格式也建议走插件路线：在 packages/markitdown-sample-plugin/ 的实现上补两个方法——accepts()判断能否处理、convert()完成转换——再注册入口点，就能独立发布，不需要改 markitdown 主仓。详细说明见 packages/markitdown-ocr/README.md。

Azure 云端服务：付费换提取质量

需要更高质量提取时，可以加-d接 Azure Document Intelligence，或用--use-cu接 Azure Content Understanding，端点通过-e/--cu-endpoint传入，也可用环境变量MARKITDOWN_DOCINTEL_ENDPOINT、MARKITDOWN_CU_ENDPOINT一次配置。两条端点都是 Azure 付费 API，适合：扫描版 PDF 的云端布局分析、复杂表格、多页长文档；Content Understanding 还能做视频（内置转换器不支持视频）和结构化字段抽取，把发票金额、合同条款这类字段以 YAML front matter 形式带在输出开头。

接进自己的流程

写自动化时直接用 Python API，核心就三行：

from markitdown import MarkItDown md = MarkItDown() print(md.convert("data.xlsx").markdown)

服务端要处理的是本地文件时，换用convert_local()，比默认的convert()入口更窄更安全——convert()设计上接受本地文件、远程 URI 和字节流，入口是故意做得宽的；只要流的话用convert_stream()。

批量转换没有专门目录模式，套一层循环即可：for f in *.pdf; do markitdown "$f" -o "out/${f%.pdf}.md"; done，逐个转当前目录的 PDF，同名.md落到out/。

常见问题

扫描版 PDF 转出来是空的，怎么解决？

内置转换器只读文字层，纯图片页面无从下手。两条出路：装markitdown-ocr插件并传llm_client，或加-d/--use-cu接云端端点。

输出的 Markdown 能当排版稿用吗？

不建议。官方定位是"给文本分析工具消费"，标题、表格、列表这类结构会保留，但像素级版面还原不在目标内，出版级转换请用专业排版工具。

某个格式报错转不了，是文件坏了吗？

先查依赖。各格式是可选装配的：没装[xlsx]时 Excel 就不可用，报的是转换失败。按需pip install 'markitdown[pdf, docx, pptx]'或干脆装[all]。

服务端直接转用户上传的文件安全吗？

markitdown 按当前进程权限做 I/O，和open()、requests.get()一个性质。输入可能来自用户时，先做路径、URI 白名单校验，并优先调convert_local()这类最窄入口，别直接喂convert()。

支持视频吗？

内置转换器没有视频支持。要转视频，走--use-cu接 Azure Content Understanding 的视频解析器。

从管道读文件，程序分不清格式怎么办？

cat example.pdf | markitdown会自动嗅探；分不出时用-x提示扩展名、-m提示 MIME 类型、-c提示编码，例如markitdown -x pdf。

和其他方案怎么选

结语

文档要进大模型、批量整理 Office、文件不能出本地——选 markitdown 本地内置就够；要扫描件的云端级提取或结构化字段，叠 OCR 插件或接 Azure 端点；追求像素级排版还原，请交给专业排版工具，不要在它身上较劲。

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