MarkItDown 完整指南：一条命令免费转换文档到 Markdown 的教程-育师

MarkItDown 完整指南：一条命令免费转换文档到 Markdown 的教程

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

MarkItDown 是一个免费开源的 Python 工具，把 PDF、Word、Excel、PPT 等办公文档用一条命令转成带结构的 Markdown，保留标题层级、表格和列表，方便直接喂给 RAG 管道和 LLM 分析。

快速上手：安装 markitdown 并跑通第一次转换 🚀

环境要求 Python 3.10 以上。安装有两种路线：装全量可选依赖，几乎所有格式开箱即用；或者只装需要的格式，依赖更干净。装完命令行一条命令完成转换，-o让结果直接落盘，不带则打印到终端方便接管道：

pip install 'markitdown[all]' markitdown report.pdf -o report.md

如果只转 PDF 和 Word，换成pip install 'markitdown[pdf, docx]'。内容从管道读入时，加-x给扩展名、-m给 MIME 类型、-c给字符集做提示，例如cat file | markitdown -x .pdf -c UTF-8。

Python 里集成只要三行，convert吃本地路径、远程地址、字节流都行：

from markitdown import MarkItDown md = MarkItDown() print(md.convert("report.xlsx").text_content)

四个真实场景：MarkItDown 能转换哪些文件

研报 PDF 进 RAG：PDF、Word 转出来保留标题层级、表格和链接，切块向量化后召回的文本语义完整。
Excel 周报做摘要：xlsx、xls、CSV 变成 Markdown 表格，LLM 直接读数字就能生成总结句，不用再解析单元格坐标。
在线链接与媒体文件：YouTube 链接以 Markdown 文本返回字幕；图片给 EXIF 元数据，音频可走语音转写。
ZIP 归档批量拆解：整包丢进去，内部文件逐个转换，适合攒了一批扫描件再统一入库。

它的定位是喂文本分析管道，不是高保真版式还原；想精确复刻页面视觉效果，去换专用排版工具。

按需开启的可选能力：LLM 描述、OCR 插件与云提取 🧩

下面这些默认都是关的，用到哪个开哪个，怎么开、代价是什么一次说清。

LLM 图片描述：图片本身没有文字时只输出 EXIF 元数据。给 MarkItDown 传入llm_client和llm_model，转换 PPT 和图片时会调大模型写一段描述塞进结果，代价是每次调用消耗 LLM API 额度。仓库里有一张专门验证该功能的测试样例图：

OCR 插件 markitdown-ocr：扫描件 PDF、图片化 Word 本地转不出字？装上插件后给 PDF、Word、PPT、Excel 补图片内文字识别，复用同一套 LLM 客户端，不传客户端时 OCR 静默跳过，配置细节见 OCR 插件说明。
Azure 云提取：-d -e <endpoint>接 Document Intelligence，--use-cu --cu-endpoint <endpoint>接 Content Understanding，后者支持结构化字段抽取（YAML front matter）且是唯一支持视频的选项，代价是每次转换都是计费的云端 API 调用。
第三方插件生态：markitdown --list-plugins看装了哪些插件，转换时加-p启用，仓库里有可直接参考的示例插件。
MCP 服务器：装上 markitdown-mcp 包，AI 助手就多了一个convert_to_markdown(uri)工具，默认只绑定本机，适合本地可信代理。

需要图片描述或 OCR 时，两者共用同一种接法：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("scanned.pdf").text_content)