MarkItDown实战：3条命令把PDF、Excel批量转成Markdown

MarkItDown实战3条命令把PDF、Excel批量转成Markdown【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdownMarkItDown 是一个用 Python 编写的文件转 Markdown 开源工具它把 PDF、Word、Excel、PPT、EPUB、HTML、图片、音频等几十种格式统一解析输出保留标题、列表、表格结构的 Markdown 文本。如果你要给 AI 准备语料、搭建个人知识库或者想批量归档办公文档它就是该先想到的那个工具。工作原理速览 文件转 Markdown 的过程可以拆成三步理解这三步后面所有用法你都能自己推导识别输入读入文件或 URL的二进制流结合扩展名、MIME 类型和 magika 的内容检测生成一个StreamInfo描述见 packages/markitdown/src/markitdown/_stream_info.py。匹配转换器框架内置一组按从通用到具体注册的转换器见 packages/markitdown/src/markitdown/_markitdown.py每个转换器先用accepts()判断自己是否该处理命中后由它执行convert()。结构化输出转换器解析原始结构返回DocumentConverterResult里面既有 Markdown 正文也带标题等元数据方便你做日志和归档。换句话说它不是把文档压扁成一段字而是逐格式地把结构翻译成 Markdown 语法。这也是为什么转出来的表格是|语法、标题是#语法——对 LLM 既熟悉又省 token。格式类别常见格式输出特点办公文档DOCX、XLSX/XLS、PPTX标题、列表、表格、链接文档/电子书PDF、EPUB、HTML保留章节层级与表格数据/文本CSV、JSON、XML文本与表格格式多媒体图片、音频、YouTubeEXIF 信息、LLM 图片描述、语音转文字压缩包ZIP逐个展开后分别转换环境准备与安装 前提是 Python 3.10 及以上。最省事的是全量安装一条命令搞定所有格式pip install markitdown[all] # 全量安装 pip install markitdown[pdf,docx,pptx] # 只需部分格式时装子集注意中括号要加引号否则部分 shell 会把它当通配符报错。想从源码安装的话git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[all]装完跑一句markitdown --help能看到帮助信息就说明成功了。最小可运行示例先跑通一条再谈其他。仓库里自带测试 PDF可以直接用markitdown packages/markitdown/tests/test_files/test.pdf -o test.md实际跑下来几秒钟就生成test.md标题层级和表格都保留。你也可以用markitdown 文件.pdf 输出.md重定向或cat 文件.pdf | markitdown从标准输入读方便接进任意管道。三个高频场景 场景 A单文件快速转换拿到一个报价单 PDF 或合同 DOCX一条命令出稿markitdown 报价单.pdf -o 报价单.md换 PPT 提取讲稿、换 Excel 转表格流程完全一样只是文件后缀不同。场景 B批量目录转换同目录下有一堆 PDF 或 Excel一个循环脚本全解决for file in *.pdf; do markitdown $file -o ${file%.pdf}.md done把*.pdf换成*.xlsx *.docx即可混批处理。路径里有空格或括号时一定要给$file加引号这个循环里已经替你加好了。场景 C嵌入 Python 工作流命令行之外MarkItDown 是标准 Python 库可以嵌进爬虫、知识库和自动化脚本from markitdown import MarkItDown md MarkItDown() result md.convert(packages/markitdown/tests/test_files/test.xlsx) print(result.text_content)返回的result同时带markdown正文和title元数据方便写日志。更进一步构造时传入llm_client和llm_model参数例如一个 OpenAI 客户端和模型名图片里的内容也能被看懂并转成文字描述排错与避坑1. 转 PDF 或 PPT 报错、输出空白现象基础安装后直接转报缺依赖或什么都没有输出。原因基础版只内置少量格式的依赖PDF/PPT 的转换器需要对应可选依赖。解法装上全量依赖pip install markitdown[all]别省这一步。2. 扫描版 PDF 转不出文字现象纯图片扫描的 PDF输出几乎为空。原因没有文字层离线解析器提不到任何字符。解法用仓库自带的 markitdown-ocr 插件或给 API 传llm_client让视觉模型读图。3. 文件名带空格或括号时命令报错现象shell 提示找不到文件或把路径拆成多段。原因shell 对空格、括号做分词处理。解法给文件名加引号如markitdown report (final).pdf。适用边界与选型建议先说清定位MarkItDown 是给机器读的工具不是高保真复刻版式的工具。该用给 LLM 准备语料、搭建个人知识库、做全文检索索引、批量归档办公资料——这些都受益于统一、省 token 的 Markdown 输出。不该用要像素级还原排版的交付文档请交给专门的排版工具。另外一句安全提醒它是以当前进程的权限读写资源的别拿它解析来路不明的文件在不可信环境里先做输入校验并优先调用范围更窄的convert_local()/convert_stream()。收尾行动卡 ✅安装pip install markitdown[all]跑通markitdown 你的文件.pdf -o 输出.md打开输出.md看结构是否保留复制场景 B 的循环脚本改成你自己的批量任务想查每个转换器的参数和插件机制翻 官方 README 和 packages/markitdown/src/markitdown/converters/ 即可。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考