5分钟看懂MarkItDown文档转换架构是怎么组织的-开发者社区

5分钟看懂MarkItDown文档转换架构是怎么组织的

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

MarkItDown 是一款把 PDF、Word、Excel、PPT、HTML 等文件转成 Markdown 的 Python 文档转换工具。本文以一条转换命令为线索，按入口、调度、转换器、插件四层拆解它的内部结构，说明它为什么既能同时支持二十多种格式，又能让你不改核心代码就新增格式。

📄 一条 markitdown 命令的完整数据流

CLI 入口在 markitdown 包的__main__.py，它只做三件事：

解析参数：文件路径、-o输出文件、--extension/--mime-type类型提示、-p是否启用插件；
创建MarkItDown实例，调用convert()传入文件路径；
把返回结果里的result.markdown写到标准输出或-o指定的文件。

调度器 _markitdown.py 里的convert()先把四种输入——本地路径、URL、HTTP 响应、二进制流——统一归一成「文件流 + 元数据」，再交给内部方法_convert()分发。整个转换过程是流进、Markdown 出，转换器不需要关心文件从哪来。

下图是测试文件目录里的一张论文页面截图，属于图片转换流水线的输入样例：

🧭 文件类型识别机制：多重候选与优先级队列

文件扩展名并不可靠，PDF 可能被重命名成 .txt。MarkItDown 的做法是多重候选：

收集三类线索：文件扩展名、HTTP 的 Content-Type 头、内容推断工具 magika（机器学习文件类型识别库）的识别结果；
把线索组合成「候选元数据列表」，互相矛盾时全部保留、按顺序逐个尝试；
在_convert()里把转换器按优先级排序（数字小者优先），依次问每个转换器的accepts()「你能处理吗」，第一个答True的调用convert()执行，抛异常则换下一个。

优先级分两档：.docx/.pdf 等具体格式转换器是 0.0，纯文本、HTML 这类兜底转换器是 10.0，放最后垫底。全部无法处理时抛出UnsupportedFormatException，明确告知格式不支持。

转换器长什么样：统一接口与 .docx 案例

转换核心集中在packages/markitdown/src/markitdown/converters/目录，每种格式一个文件，如_docx_converter.py、_pdf_converter.py，全部继承同一个基类 DocumentConverter：

class DocumentConverter: """Abstract superclass of all DocumentConverters.""" def accepts(self, file_stream, stream_info, **kwargs) -> bool: # 判断本转换器能否处理当前文件 raise NotImplementedError def convert(self, file_stream, stream_info, **kwargs) -> DocumentConverterResult: # 执行转换，返回 Markdown 与元数据 raise NotImplementedError

两个方法就是转换器与调度器之间的全部契约。看.docx的实现：DocxConverter继承的不是基类而是HtmlConverter——Word 文档先做预处理转成 HTML，再走 HTML 转 Markdown 的既有管道，复杂数学公式由 converter_utils 下的 OMML→LaTeX 工具处理。转换器之间也能互相继承、复用逻辑。

图片输入由ImageConverter负责：先用 exiftool 提取 EXIF 元数据（标题、作者等），配置了多模态 LLM 时再生成文字描述。下图就是项目里用于 LLM 图片描述的测试文件：

🧩 新增一种格式要改哪些文件：3步流程

以官方示例插件 markitdown-sample-plugin（新增 RTF 支持）为例：

写一个继承DocumentConverter的类，实现accepts()（检查扩展名/MIME）和convert()（执行转换）；
在包里声明register_converters(markitdown)函数，内部调用markitdown.register_converter()注册；
在pyproject.toml声明markitdown.plugin组下的插件入口点。pip 安装后，核心库通过 entry point 机制自动扫描并加载，核心代码一行未动。

装好后用markitdown --list-plugins查看已装插件，加-p参数启用。RTF 示例插件全文不到百行，是写插件最好的模板。

OCR 包 markitdown-ocr 展示了进阶玩法：它以-1.0的优先级注册增强版 PDF/Word/PPT/Excel 转换器，跑在内置转换器（0.0）之前，等于整体替换标准版本，内置代码依然不动。