markitdown 文档转 Markdown 源码

这套源码是一个 Python 文件转换工具，主要把各种文档和办公文件转成 Markdown 文本。

项目来自 GitHub 开源仓库 microsoft/markitdown，由微软维护，当前版本 0.1.6，采用 MIT 开源协议。

源码简介

这套源码属于 Python 文档转换工具项目，核心是把 PDF、Office、网页、邮件等文件统一转成 Markdown。

它提供一个命令行工具和 Python 库，输入一个文件或 URL，就能拿到结构化的 Markdown 文本。

对做文档处理、知识库入库、检索增强生成预处理的人来说，这份源码提供了完整可用的实现。

仓库是 monorepo 结构，除主库外还包含 markitdown-mcp、markitdown-ocr 与示例插件等子包。

适用场景

• 学习 Python 多格式文档解析、格式识别与 Markdown 转换的实现思路
• 搭建本地文档批量转 Markdown 的脚本，用于知识库或检索增强生成预处理
• 基于插件机制和 MCP 服务器做二次开发，把转换能力接入自有流程或 AI 工具

技术栈与运行环境

• 前端：无前端界面，提供命令行与 Python API
• 后端：Python 库，要求 Python >= 3.10（支持 3.10–3.13 与 PyPy）
• 数据库：无数据库依赖，转换结果直接输出为 Markdown 文本
• 运行环境：核心依赖 beautifulsoup4、requests、markdownify、magika、charset-normalizer、defusedxml；各格式按需安装可选依赖
• 其他依赖：PDF/PPT/Excel/Word 等分别依赖 pdfminer.six、python-pptx、pandas、mammoth 等；官方提供 Docker 镜像，采用 hatchling 构建

功能亮点

• 多格式转 Markdown：内置 20 多种转换器，覆盖 DOCX、PPTX、XLSX/XLS、PDF、HTML、CSV、EPUB、Outlook 邮件、ZIP、纯文本、IPYNB 等（packages/markitdown/src/markitdown/converters 目录）
• 智能类型识别：用 Magika 做内容层面的文件类型猜测，并用 charset-normalizer 识别文本编码，弱扩展名也能选对转换器（_markitdown.py 中 Magika 与 _get_stream_info_guesses）
• 插件扩展机制：通过 Python entry_points（group=markitdown.plugin）加载第三方转换器，仓库自带 markitdown-sample-plugin 与 markitdown-ocr 示例（_markitdown.py 的 _load_plugins 与 enable_plugins）
• 图片描述与 OCR：图片转换器可提取 exiftool 元数据，并调用多模态 LLM 生成图像说明；markitdown-ocr 插件还能用 LLM 视觉能力识别内嵌图片文字（converters/_image_converter.py）
• 命令行与 Python API：命令行支持文件直转、管道输入、按扩展名或 MIME 过滤、启用插件等参数；Python 端用 MarkItDown().convert() 一行调用（__main__.py 与 _markitdown.py）
• 云端与 MCP 集成：可选接入 Azure Document Intelligence / Content Understanding 做高质量结构化抽取，另含 markitdown-mcp 子包把转换能力封装为 MCP 服务器（packages/markitdown-mcp）

安装与部署提示

1. 需要 Python 3.10 及以上环境，建议用虚拟环境隔离依赖
2. 基础安装：pip install markitdown，再按格式按需安装可选依赖，例如 pip install ‘markitdown[pdf,docx,pptx]’
3. 命令行转换：markitdown 文件.pdf -o 输出.md，或 cat 文件.pdf | markitdown 走管道
4. 启用第三方插件可加 –use-plugins，查看已安装插件用 –list-plugins
5. 使用 LLM 图像说明或云端抽取时需自行配置 llm_client 与云端点，具体参数以仓库 README 为准

常见问题

运行前需要注意什么？

Python 版本需不低于 3.10，不同文件格式要安装对应可选依赖，否则该格式会提示不支持。

图片说明与云端抽取属于可选能力，需要额外配置 LLM 客户端或 Azure 端点，建议先看 README 的 Installation 与 Optional Dependencies 章节。

适合二次开发吗？

适合。

源码结构清晰，转换器统一继承 DocumentConverter 基类并通过 register_converter 注册，类型识别、插件加载与优先级调度逻辑完整，便于新增格式或接入自有流程。

安全风险提示

特别提示：本源码未检测安全风险文件，下载后请务必进行安全审计，删除恶意代码后再部署使用！

下载说明

源码仅供学习研究、测试部署和二次开发参考，商用前请自行确认授权、版权和安全风险。

使用本工具处理他人文档时，请遵守相关隐私与数据合规要求，涉及云端点或 LLM 接口时妥善保管密钥，勿将敏感文件上传至未经授权的第三方服务。

GitHub开源地址：https://github.com/microsoft/markitdown