一行命令把 PDF、Word、Excel 变成 Markdown：MarkItDown 完整实战指南

一行命令把 PDF、Word、Excel 变成 MarkdownMarkItDown 完整实战指南【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdownMarkItDown 是一个用 Python 编写的开源工具负责把各类文件与办公文档转成 Markdown。一条命令即可把 PDF、Word、Excel、PPT 变成带标题、列表、表格的结构化文本适合给大模型准备语料或搭建个人知识库。快速上手MarkItDown 安装命令与首次转换验证 目标是三分钟跑通。MarkItDown 需要 Python 3.10 及以上先装全量可选依赖注意方括号要加引号否则部分 shell 会把它当通配符报错pip install markitdown[all]装好后拿一份 PDF 完成第一次转换用-o指定输出文件还能避开重定向在 Windows 终端里的编码问题markitdown report.pdf -o report.md打开report.md看一眼章节变成了#层级标题表格变成 Markdown 表格语法结构完整保留。想从源码验证也可以克隆仓库后以可编辑模式安装git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[all]核心能力文件转 Markdown 的 4 个使用场景办公文档散件变成可检索语料团队盘里躺着几十份会议纪要 PDF 和需求文档 Word想找内容只能逐个点开。把每份转成 Markdown 再丢进检索索引就能直接全文搜索命令对所有格式完全一致markitdown meeting.pdf -o meeting.md批量转换 Excel 的方法季度报表里有二三十张 Excel 表逐个敲命令显然不现实一个 shell 循环扫完整个目录。我上次用这个循环处理了 26 张数据表表头和列结构都保留完整产出直接进了知识库for file in q3/*.xlsx; do markitdown $file -o ${file%.xlsx}.md done网页与数据文件进同一条管道抓回来的 HTML 页面、RSS 订阅源还有 CSV、JSON、XML 这类数据文件走同一条命令就能进管道不必给每种来源单独写解析逻辑markitdown article.html -o article.md图片、音频、视频链接也变成文字图片会转成 EXIF 元数据文本音频可以语音转文字需安装audio-transcription可选依赖YouTube 链接直接给也能拿回字幕文本ZIP 压缩包则自动拆开逐个处理。最短演示markitdown interview.wav -o interview.md进阶整合把 MarkItDown Python API 嵌进自己的脚本命令行够偶尔用但转换一旦变成日常流程就该让 Python API 出场。爬虫、定时任务、知识库更新脚本都可以直接调一个函数完成整段工作from markitdown import MarkItDown md MarkItDown() result md.convert(q3-report.xlsx) print(result.markdown)返回值不是裸字符串而是带markdown、title等元数据的 result 对象做日志归档很方便。如果场景只涉及本地文件建议直接调convert_local()比通用的convert()攻击面更小。接上视觉模型让扫描页和图片被读懂仓库里自带markitdown-ocr插件源码在 packages/markitdown-ocr它会把 PDF、Word、PPT、Excel 中内嵌的图片提取出来发给视觉模型识别再把文字插回原文位置整页扫描的 PDF 也能逐页兜底恢复。装好插件和一个 OpenAI 兼容客户端把模型传进去即可from markitdown import MarkItDown from openai import OpenAI md MarkItDown(enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o) print(md.convert(scan.pdf).markdown)不传llm_client时插件会静默跳过、回落到离线转换器代码不会因此报错。常见问题3 个转换报错的原因与解法 用了一段时间我反复撞见过这三类问题按现象 → 原因 → 解法给你备着转 PDF/PPT 直接报错或输出是空的→ 这些格式属于可选依赖裸装只有基础转换器 → 安装pip install markitdown[all]或按需装最小集合pip install markitdown[pdf, docx, pptx]。扫描版 PDF 转出来几乎没文字→ 离线转换器只提取文本层扫描页里全是图片 → 安装markitdown-ocr插件并按上文接入视觉模型。从标准输入读取时报没有可用转换器→ 没有文件名就无法推断扩展名与 MIME → 用-x参数显式给出类型提示cat scan.pdf | markitdown -x pdf另外记住一条路径里带空格或括号时命令行务必给文件名加引号否则 shell 会拆词。边界MarkItDown 适合什么与不适合什么MarkItDown 的定位是给机器读LLM 语料、RAG 索引、检索归档、批量结构提取是它的主场如果你要的是像素级还原版式或印刷级排版别硬凑交给专门的排版工具。另有一件事必须留意——它按当前进程的权限读写资源不要拿它直接解析来路不明的文件服务端场景请先校验输入并优先调用convert_local()或convert_stream()。挑一份你压着没整理的 PDF装好依赖、一行命令转掉你的知识库就少一个欠账主包 README安装、可选依赖与完整用法OCR 插件文档视觉模型识别细节与故障排查【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考