企业官网建设流程全解析

MarkItDown 文档转换实战：把 PDF、Word、Excel 快速变成 Markdown

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

当你需要把一份合同 PDF、一份 Excel 报表或 PPT 交给大模型分析时，得先把它变成干净的 Markdown。MarkItDown 就是一个 Python 文档转换工具，一行命令或几行代码，把各种文件和 Office 文档转成 Markdown，让你把精力放在内容本身，而不是解析细节上。

首次体验：安装 MarkItDown 并两分钟看到转换结果

先装包，[all]会带上 PDF、Word、Excel、PPT 等格式的解析依赖：

pip install 'markitdown[all]'

装完就有了markitdown命令，直接用仓库里自带的测试文件跑一下：

markitdown packages/markitdown/tests/test_files/test.pdf -o out.md

想用 Python 调用的话，也只需要三行：

from markitdown import MarkItDown md = MarkItDown() result = md.convert("packages/markitdown/tests/test_files/test.xlsx") print(result.markdown) # 完整 Markdown print(result.text_content) # 纯文本，可直接喂给大模型

到这里，第一次转换就完成了——没有配置文件，不需要 API key。

为什么值得用：和手工做法对比一下

如果每种格式都自己接不同的库，你会很快厌烦。MarkItDown 的差异点很具体：

更关键的是输出去向：标题层级、列表、表格、图片引用都被转成大模型能直接解析的 Markdown 元素，而不仅仅是"人能读"。

核心功能实战：四个高频转换任务

命令行转换 PDF 报告

把一份合同 PDF 丢给大模型前，一条命令就够：

markitdown contract.pdf > contract.md

文件不在本地也没关系，支持管道输入：cat report.pdf | markitdown，也可以传 URL 直接转网页。

批量转换一个文件夹的 Office 文档

假设你有一个存满月度报表的文件夹，要整体转成 Markdown 再交给大模型出总结。复用一个MarkItDown实例循环处理：

import os from markitdown import MarkItDown md = MarkItDown() folder = "./reports" for name in os.listdir(folder): path = os.path.join(folder, name) if os.path.isfile(path): result = md.convert(path) with open(f"{name}.md", "w", encoding="utf-8") as f: f.write(result.markdown)

xlsx、docx、pptx 混在一起也没问题，它会按文件选对应的转换器。

处理没有扩展名、或编码不确定的文件

从接口下载的文件常常没有扩展名，此时给命令行一个提示即可：

cat data.bin | markitdown -x .pdf

编码不对导致乱码时，用markitdown file.txt -c utf-8指定；Python 接口里对应传一个StreamInfo对象。

给扫描版 PDF 加上 OCR

内置解析只认"天生数字"的文件，扫描件要装官方 OCR 插件：

pip install markitdown-ocr openai

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown( enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o", ) result = md.convert("scan.pdf")

插件用视觉大模型识别 PDF、Word、PPT、Excel 内嵌图片里的文字，没提供llm_client时会自动回退到内置转换器，不会报错。

常见坑与实用技巧 💡

• 转换时报MissingDependencyException或提示缺模块：这是新手最常踩的坑。核心包只带 HTML、CSV、纯文本等基础能力，PDF、Word、Excel 要用 extras 打开，比如pip install 'markitdown[pdf,docx]'，嫌麻烦就pip install 'markitdown[all]'一次装全。
• 无扩展名的文件识别失败：用-x .pdf给扩展名提示，-m application/pdf给 MIME 提示；从 stdin 读入时 magika 会按内容自动检测，通常不用猜。
• 输出里塞满超长的 base64 字符串：默认行为是把 data URI 截断，避免 Markdown 膨胀；只有你确实要保留内嵌图片时才加--keep-data-uris。
• 音频转录不生效：音频格式依赖audio-transcription这个 extra，底层 SpeechRecognition 还依赖系统环境，建议先装markitdown[audio-transcription]再测。
• 安全提醒：MarkItDown 以当前进程权限访问文件和网络资源，处理不可信输入时先做校验，并优先调用范围更窄的convert_local()/convert_stream()，而不是直接convert()任意路径。

进阶扩展：给你的场景加一种转换格式

插件机制基于 Python entry points：包只要在markitdown.plugin组下注册，MarkItDown 启动时就会自动发现，命令行加-p、代码里传enable_plugins=True即启用。思路是继承DocumentConverter基类，用accepts()声明你负责哪些文件、用convert()返回DocumentConverterResult。仓库里附带最小样例 packages/markitdown-sample-plugin/，插件实现可以对照 OCR 插件 packages/markitdown-ocr/ 看，内置转换器的完整逻辑都在 packages/markitdown/src/markitdown/converters/ 里。部署方面，仓库根目录有现成的 Dockerfile 可直接构建镜像。

收尾

MarkItDown 让多格式文档到 LLM 友好 Markdown 的转换只剩一条命令。现在就动手：pip install 'markitdown[all]'，再用markitdown 你的文件.pdf > out.md转出第一份结果。

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