MarkItDown 5 分钟上手20 种办公文档转 Markdown 完整指南【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdownMarkItDown 是一个轻量级 Python 文档转换工具能把 PDF、Word、Excel、PPT、图片、音频、HTML、EPUB、Notebook 等 20 多种格式统一转成结构化 Markdown专为喂给大模型和文本分析管线设计。如果你正被一堆格式各异的文档进不了 LLM 上下文这件事卡住它值得你花 5 分钟跑通第一个例子。它到底能转什么能力地图先给结论办公套件、文本类、媒体类三类格式全覆盖且转换时会尽量保留标题、列表、表格、链接这些结构而不是丢出一坨纯文本。类别支持格式转出来的东西办公文档PDF、Word.docx、Excel.xlsx/.xls、PPT.pptx、Outlook 邮件.msg带标题层级和表格的 Markdown文本/数据CSV、JSON、XML、HTML、RSS、EPUB、Jupyter Notebook结构化 Markdown 或表格媒体图片EXIF 元数据 可选 LLM 图注、音频元数据 可选语音转写、YouTube 链接元数据信息 可选识别文本其他ZIP逐个遍历内部文件递归转换后的拼接结果实现上它不是一个大而全的解析器而是一张转换器注册表每种格式对应一个独立 Converter源码在packages/markitdown/src/markitdown/converters/按优先级排序后逐个尝试——专用格式优先级高text/*这类通用兜底转换器排在后面。文件类型识别用的是 magika所以扩展名写错了、甚至从管道读入无扩展名流多数情况下也能认出来。这个设计带来两个直接好处只装需要的格式依赖见后文 extras以及第三方可以用插件形式加新格式不需要改核心代码。5 分钟跑通第一个转换要求 Python 3.10建议先建虚拟环境然后一条命令装全量格式依赖pip install markitdown[all][all]会装齐所有格式依赖。如果只需要 PDF 和 Word装pip install markitdown[pdf, docx]更省空间可选的 extras 包括[pdf]、[docx]、[xlsx]、[pptx]、[xls]、[outlook]、[audio-transcription]、[youtube-transcription]、[az-doc-intel]、[az-content-understanding]。装完直接在命令行转文件markitdown example.pdf -o example.md-o省略时结果打到标准输出所以markitdown example.pdf example.md也行内容也可以从管道喂进去cat example.pdf | markitdown同样成立。Python 侧 API 更简单三行拿到 Markdown 文本from markitdown import MarkItDown md MarkItDown() result md.convert(quarter_data.xlsx) print(result.text_content)这段代码做的事实例化转换器调用convert()传入文件路径从结果对象里取 Markdown 文本。后面所有场景都是这两行的变体。典型实战三个真实场景场景一本地文档库批量进 LLM你会遇到API 文档、季度报表、论文 PDF 散落在本地想批量转成 Markdown 存库再拼进大模型的上下文。怎么操作遍历目录逐个转换顺手处理失败文件——convert()抛异常时不要中断整个批次from pathlib import Path from markitdown import MarkItDown from markitdown import FileConversionException md MarkItDown() for f in Path(docs).glob(**/*.{pdf,docx,xlsx,pptx}): try: out f.with_suffix(.md) out.write_text(md.convert(str(f)).text_content, encodingutf-8) except FileConversionException: print(f跳过无法转换的文件: {f})跑出来什么效果每个源文件旁边多一个同名.md标题层级、表格、列表都保留了可以直接喂 RAG 管线。项目仓库里的测试样本packages/markitdown/tests/test_files/就是一篇完整的论文 PDF转出来第一页长这样一个实用技巧PPT 里的图片默认只能输出元数据。给MarkItDown()传llm_client和llm_model转换时会把图片发给大模型生成描述并写进 MarkdownPPT 转写立刻从文字图注占位变成文字图的内容描述from openai import OpenAI md MarkItDown(llm_clientOpenAI(), llm_modelgpt-4o) result md.convert(example.pptx)下面这张就是项目测试用的图注素材——图内文字会明确提示模型注意红色圆形和蓝色正方形场景二扫描件 PDF 的文字识别你会遇到扫描版发票、老合同页面上根本没有文本层内置转换器转出来是空的。怎么操作装官方 OCR 插件源码在packages/markitdown-ocr/它复用同一个llm_client机制用 LLM Vision 从嵌入图片里抽文字不需要额外装 Tesseract 之类的二进制依赖pip install markitdown-ocr openaifrom markitdown import MarkItDown from openai import OpenAI md MarkItDown(enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o) result md.convert(scanned_invoice.pdf) print(result.text_content)跑出来什么效果嵌在 PDF 里的图片会按版面顺序插回正文识别出的文字用*[Image OCR] ... [End OCR]*包裹整页扫描无可提取文本层的页面会自动按 300 DPI 渲染整页送识别识别结果保留原有文档流。任何 OpenAI 兼容接口含 Azure都能接。⚠️ 两个静默行为要留意没传llm_client时插件照加载但 OCR 直接跳过回退到内置转换器——所以转出来没文字第一排查点就是这里单次 LLM 调用失败也只告警不中断个别图识别失败不影响整体转换。场景三把转换能力挂给你的 Agent你会遇到你自己搭了 AI 应用或 Agent希望它能看到文件就自动转 Markdown而不想每个项目里重复写转换代码。怎么操作官方提供了 MCP 服务器包packages/markitdown-mcp/只暴露一个工具convert_to_markdown(uri)支持 STDIO、Streamable HTTP、SSE 三种传输pip install markitdown-mcp markitdown-mcp # 默认 STDIO markitdown-mcp --http --port 3001 # HTTP 模式在 Claude Desktop 等 MCP 客户端里把markitdown-mcp配成 command 即可Docker 运行方式docker run --rm -i markitdown-mcp:latest见该包自带的 README。跑出来什么效果Agent 侧直接对file:、http(s):、data:URI 发起转换文档处理变成 Agent 的原生工具调用。调优与避坑你大概率会踩的坑先给你一张 CLI 常用参数表来自packages/markitdown/src/markitdown/__main__.py的完整参数集参数作用什么时候用-o, --output指定输出文件不想用重定向时-x, --extension手动提示扩展名如pdf从 stdin 读、扩展名识别不准时-m, --mime-type提示 MIME 类型同上按类型而非扩展名兜底-c, --charset提示字符集如UTF-8文本文件乱码时-p, --use-plugins启用第三方插件用 OCR 等插件转换器时必须加--list-plugins列出已安装插件排查插件没加载--keep-data-uris保留 base64 内嵌资源默认会截断 data URI需要时再开-d, --use-docintel-e走 Azure Document Intelligence 云端提取本地效果不佳的复杂文档--use-cu--cu-endpoint走 Azure Content Understanding支持音视频和结构化字段抽取需要 YAML front matter 字段、或要转视频⚠️坑 1报不支持的格式多半是依赖没装。MarkItDown 按 extras 懒装解析器裸pip install markitdown只有基础文本格式可用。转 PDF 前先确认装了[pdf]。⚠️坑 2插件默认是关的。装了markitdown-ocr却不加-pPython 里enable_pluginsTrueOCR 根本不会生效且不会报任何错——用markitdown --list-plugins确认插件在列后再转换。坑 3图片元数据依赖 exiftool。转换图片/音频的 EXIF 信息需要系统里有 exiftool路径找不到时可通过exiftool_path参数或EXIFTOOL_PATH环境变量显式指定。⚠️坑 4安全别大意。convert()会接受本地路径、远程 URI 和字节流用的是当前进程权限。服务端应用里处理不可信输入时改用更窄的convert_local()或convert_stream()并在 README 的 Security Considerations 一节里对照检查。坑 5大 PDF 想控制成本。接了 Azure 端点时cu_file_types可以限定哪些格式走云端计费接口如只让 PDF 走其余留在本地转换。横向对比和 Pandoc、textract 比怎么选维度MarkItDownPandoctextract输出定位喂 LLM/文本分析的结构化 Markdown面向人类阅读的富文档转换提取纯文本结构保留标题、列表、表格、链接很强弱格式覆盖20含 EPUB、Notebook、音频、YouTube40偏文档互转常见办公格式为主LLM 协作原生llm_client图注 OCR 插件无无扩展方式entry-point 插件 MCP 服务器过滤器/自定义读取器有限部署形态pip / Docker / MCP命令行二进制pip一句话总结差异要文档之间互相转选 Pandoc只要把字抠出来选 textract要把文档变成大模型好消化的 Markdown并且保留结构、能接插件和 MCP就是 MarkItDown 的场。生态与社区文档主包 README 覆盖了安装、CLI、Python API、Azure 集成和测试方法路径packages/markitdown/README.mdOCR 插件另有独立文档packages/markitdown-ocr/README.md。插件机制想加新格式照着packages/markitdown-sample-plugin/写一个DocumentConverter实现accepts()和convert()两个方法在pyproject.toml注册markitdown.pluginentry point 即可——核心库按 entry point 懒加载优先级数字越小越先尝试内置专用转换器是 0.0插件可以用 -1.0 插队替换。MCP 生态packages/markitdown-mcp/独立成包STDIO/HTTP/SSE 三种传输方便接 Claude Desktop 等客户端。反馈渠道项目 Issues 区会标记 open for contribution / open for reviewing 的任务适合第一次提 PR 的开发者找入口社区找第三方插件的约定是搜#markitdown-plugin标签。测试即文档packages/markitdown/tests/test_files/里备好了 PDF、docx、pptx、xlsx、EPUB、音频、Notebook 全套样例想验证某个格式的效果直接拿这些文件试比自己找素材快。写在最后MarkItDown 解决的就一件事把各种格式的文档变成大模型愿意读、结构没丢的 Markdown。做 RAG、搭文档问答、写内容处理管线或者只是想让 Agent 自己会读文件的开发者装完[all]、敲两行代码就能用上要更高保真的扫描件识别和云端提取再按需求叠 OCR 插件或 Azure 端点即可。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MarkItDown 5 分钟上手：20+ 种办公文档转 Markdown 完整指南
MarkItDown 5 分钟上手20 种办公文档转 Markdown 完整指南【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdownMarkItDown 是一个轻量级 Python 文档转换工具能把 PDF、Word、Excel、PPT、图片、音频、HTML、EPUB、Notebook 等 20 多种格式统一转成结构化 Markdown专为喂给大模型和文本分析管线设计。如果你正被一堆格式各异的文档进不了 LLM 上下文这件事卡住它值得你花 5 分钟跑通第一个例子。它到底能转什么能力地图先给结论办公套件、文本类、媒体类三类格式全覆盖且转换时会尽量保留标题、列表、表格、链接这些结构而不是丢出一坨纯文本。类别支持格式转出来的东西办公文档PDF、Word.docx、Excel.xlsx/.xls、PPT.pptx、Outlook 邮件.msg带标题层级和表格的 Markdown文本/数据CSV、JSON、XML、HTML、RSS、EPUB、Jupyter Notebook结构化 Markdown 或表格媒体图片EXIF 元数据 可选 LLM 图注、音频元数据 可选语音转写、YouTube 链接元数据信息 可选识别文本其他ZIP逐个遍历内部文件递归转换后的拼接结果实现上它不是一个大而全的解析器而是一张转换器注册表每种格式对应一个独立 Converter源码在packages/markitdown/src/markitdown/converters/按优先级排序后逐个尝试——专用格式优先级高text/*这类通用兜底转换器排在后面。文件类型识别用的是 magika所以扩展名写错了、甚至从管道读入无扩展名流多数情况下也能认出来。这个设计带来两个直接好处只装需要的格式依赖见后文 extras以及第三方可以用插件形式加新格式不需要改核心代码。5 分钟跑通第一个转换要求 Python 3.10建议先建虚拟环境然后一条命令装全量格式依赖pip install markitdown[all][all]会装齐所有格式依赖。如果只需要 PDF 和 Word装pip install markitdown[pdf, docx]更省空间可选的 extras 包括[pdf]、[docx]、[xlsx]、[pptx]、[xls]、[outlook]、[audio-transcription]、[youtube-transcription]、[az-doc-intel]、[az-content-understanding]。装完直接在命令行转文件markitdown example.pdf -o example.md-o省略时结果打到标准输出所以markitdown example.pdf example.md也行内容也可以从管道喂进去cat example.pdf | markitdown同样成立。Python 侧 API 更简单三行拿到 Markdown 文本from markitdown import MarkItDown md MarkItDown() result md.convert(quarter_data.xlsx) print(result.text_content)这段代码做的事实例化转换器调用convert()传入文件路径从结果对象里取 Markdown 文本。后面所有场景都是这两行的变体。典型实战三个真实场景场景一本地文档库批量进 LLM你会遇到API 文档、季度报表、论文 PDF 散落在本地想批量转成 Markdown 存库再拼进大模型的上下文。怎么操作遍历目录逐个转换顺手处理失败文件——convert()抛异常时不要中断整个批次from pathlib import Path from markitdown import MarkItDown from markitdown import FileConversionException md MarkItDown() for f in Path(docs).glob(**/*.{pdf,docx,xlsx,pptx}): try: out f.with_suffix(.md) out.write_text(md.convert(str(f)).text_content, encodingutf-8) except FileConversionException: print(f跳过无法转换的文件: {f})跑出来什么效果每个源文件旁边多一个同名.md标题层级、表格、列表都保留了可以直接喂 RAG 管线。项目仓库里的测试样本packages/markitdown/tests/test_files/就是一篇完整的论文 PDF转出来第一页长这样一个实用技巧PPT 里的图片默认只能输出元数据。给MarkItDown()传llm_client和llm_model转换时会把图片发给大模型生成描述并写进 MarkdownPPT 转写立刻从文字图注占位变成文字图的内容描述from openai import OpenAI md MarkItDown(llm_clientOpenAI(), llm_modelgpt-4o) result md.convert(example.pptx)下面这张就是项目测试用的图注素材——图内文字会明确提示模型注意红色圆形和蓝色正方形场景二扫描件 PDF 的文字识别你会遇到扫描版发票、老合同页面上根本没有文本层内置转换器转出来是空的。怎么操作装官方 OCR 插件源码在packages/markitdown-ocr/它复用同一个llm_client机制用 LLM Vision 从嵌入图片里抽文字不需要额外装 Tesseract 之类的二进制依赖pip install markitdown-ocr openaifrom markitdown import MarkItDown from openai import OpenAI md MarkItDown(enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o) result md.convert(scanned_invoice.pdf) print(result.text_content)跑出来什么效果嵌在 PDF 里的图片会按版面顺序插回正文识别出的文字用*[Image OCR] ... [End OCR]*包裹整页扫描无可提取文本层的页面会自动按 300 DPI 渲染整页送识别识别结果保留原有文档流。任何 OpenAI 兼容接口含 Azure都能接。⚠️ 两个静默行为要留意没传llm_client时插件照加载但 OCR 直接跳过回退到内置转换器——所以转出来没文字第一排查点就是这里单次 LLM 调用失败也只告警不中断个别图识别失败不影响整体转换。场景三把转换能力挂给你的 Agent你会遇到你自己搭了 AI 应用或 Agent希望它能看到文件就自动转 Markdown而不想每个项目里重复写转换代码。怎么操作官方提供了 MCP 服务器包packages/markitdown-mcp/只暴露一个工具convert_to_markdown(uri)支持 STDIO、Streamable HTTP、SSE 三种传输pip install markitdown-mcp markitdown-mcp # 默认 STDIO markitdown-mcp --http --port 3001 # HTTP 模式在 Claude Desktop 等 MCP 客户端里把markitdown-mcp配成 command 即可Docker 运行方式docker run --rm -i markitdown-mcp:latest见该包自带的 README。跑出来什么效果Agent 侧直接对file:、http(s):、data:URI 发起转换文档处理变成 Agent 的原生工具调用。调优与避坑你大概率会踩的坑先给你一张 CLI 常用参数表来自packages/markitdown/src/markitdown/__main__.py的完整参数集参数作用什么时候用-o, --output指定输出文件不想用重定向时-x, --extension手动提示扩展名如pdf从 stdin 读、扩展名识别不准时-m, --mime-type提示 MIME 类型同上按类型而非扩展名兜底-c, --charset提示字符集如UTF-8文本文件乱码时-p, --use-plugins启用第三方插件用 OCR 等插件转换器时必须加--list-plugins列出已安装插件排查插件没加载--keep-data-uris保留 base64 内嵌资源默认会截断 data URI需要时再开-d, --use-docintel-e走 Azure Document Intelligence 云端提取本地效果不佳的复杂文档--use-cu--cu-endpoint走 Azure Content Understanding支持音视频和结构化字段抽取需要 YAML front matter 字段、或要转视频⚠️坑 1报不支持的格式多半是依赖没装。MarkItDown 按 extras 懒装解析器裸pip install markitdown只有基础文本格式可用。转 PDF 前先确认装了[pdf]。⚠️坑 2插件默认是关的。装了markitdown-ocr却不加-pPython 里enable_pluginsTrueOCR 根本不会生效且不会报任何错——用markitdown --list-plugins确认插件在列后再转换。坑 3图片元数据依赖 exiftool。转换图片/音频的 EXIF 信息需要系统里有 exiftool路径找不到时可通过exiftool_path参数或EXIFTOOL_PATH环境变量显式指定。⚠️坑 4安全别大意。convert()会接受本地路径、远程 URI 和字节流用的是当前进程权限。服务端应用里处理不可信输入时改用更窄的convert_local()或convert_stream()并在 README 的 Security Considerations 一节里对照检查。坑 5大 PDF 想控制成本。接了 Azure 端点时cu_file_types可以限定哪些格式走云端计费接口如只让 PDF 走其余留在本地转换。横向对比和 Pandoc、textract 比怎么选维度MarkItDownPandoctextract输出定位喂 LLM/文本分析的结构化 Markdown面向人类阅读的富文档转换提取纯文本结构保留标题、列表、表格、链接很强弱格式覆盖20含 EPUB、Notebook、音频、YouTube40偏文档互转常见办公格式为主LLM 协作原生llm_client图注 OCR 插件无无扩展方式entry-point 插件 MCP 服务器过滤器/自定义读取器有限部署形态pip / Docker / MCP命令行二进制pip一句话总结差异要文档之间互相转选 Pandoc只要把字抠出来选 textract要把文档变成大模型好消化的 Markdown并且保留结构、能接插件和 MCP就是 MarkItDown 的场。生态与社区文档主包 README 覆盖了安装、CLI、Python API、Azure 集成和测试方法路径packages/markitdown/README.mdOCR 插件另有独立文档packages/markitdown-ocr/README.md。插件机制想加新格式照着packages/markitdown-sample-plugin/写一个DocumentConverter实现accepts()和convert()两个方法在pyproject.toml注册markitdown.pluginentry point 即可——核心库按 entry point 懒加载优先级数字越小越先尝试内置专用转换器是 0.0插件可以用 -1.0 插队替换。MCP 生态packages/markitdown-mcp/独立成包STDIO/HTTP/SSE 三种传输方便接 Claude Desktop 等客户端。反馈渠道项目 Issues 区会标记 open for contribution / open for reviewing 的任务适合第一次提 PR 的开发者找入口社区找第三方插件的约定是搜#markitdown-plugin标签。测试即文档packages/markitdown/tests/test_files/里备好了 PDF、docx、pptx、xlsx、EPUB、音频、Notebook 全套样例想验证某个格式的效果直接拿这些文件试比自己找素材快。写在最后MarkItDown 解决的就一件事把各种格式的文档变成大模型愿意读、结构没丢的 Markdown。做 RAG、搭文档问答、写内容处理管线或者只是想让 Agent 自己会读文件的开发者装完[all]、敲两行代码就能用上要更高保真的扫描件识别和云端提取再按需求叠 OCR 插件或 Azure 端点即可。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考