MarkItDown 实战指南：一条命令把 PDF、Word、PPT 转成 Markdown，扫描件也能提字

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

手头同时有 PDF、Word、Excel、PPT，却要喂给同一条 LLM 流水线？文档转 Markdown 工具 MarkItDown 就是干这个的：输入一个文件，输出带结构的 Markdown，标题、列表、表格、链接都保留下来。适合需要把一堆异构文档统一成一种文本格式的开发者。

从安装到第一个 Markdown 要多久

环境要求 Python 3.10 及以上（3.14 以内）。推荐建个虚拟环境，然后一条命令装齐全部可选依赖：

pip install 'markitdown[all]'

装完立刻能转：

markitdown report.pdf -o report.md

不想落盘就重定向到 stdout；cat report.pdf | markitdown也能走管道输入。确认成功的办法很直接：打开report.md，检查原文里的章节标题有没有变成#层级、表格有没有以 Markdown 表格呈现。能对上，就算跑通了。

谁在干活：每种格式一个独立转换器

打开源码就明白它为什么"不挑格式"。所有转换器平铺在 converters 目录，一个文件管一个格式：

• _docx_converter.py：Word
• _pdf_converter.py：PDF
• _xlsx_converter.py：Excel
• _pptx_converter.py：PowerPoint

调用时 MarkItDown 按文件扩展名路由到对应模块，你不用关心背后是谁。每个转换器负责把该格式特有的结构映射成 Markdown 语法——Word 的标题样式变成#层级，列表保持列表语法，表格输出为 Markdown 表格，超链接保留 URL。

超出"纯格式转换"的三块能力

扫描件没有文本层，怎么把图里的字提出来

扫描件 PDF 整页是图，没有可提取的文本。markitdown-ocr插件解决的就是这一环：它会处理 PDF、DOCX、PPTX、XLSX 中内嵌的图片，把文字交给视觉模型提取。整页无文本的扫描 PDF 会被自动识别，每页以 300 DPI 渲染成整页图片再送模型。

仓库里现成的扫描票据测试文件 RECEIPT-2024-TXN-98765_retail_purchase.pdf 和它的预期输出 RECEIPT-2024-TXN-98765_retail_purchase.md，可以直接拿来验证这条链路。

安装与启用都在 Python 侧完成：

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

提取出的文字会包在*[Image OCR]...[End OCR]*标记里，插回原文对应位置。一个容易忽略的点：不传llm_client时插件照样加载，但 OCR 被静默跳过，回退到内置转换器。详细行为见 markitdown-ocr 插件文档。

图片本身转不成文字，让视觉模型代写描述

图片没法"转换"，但可以在输出里为它生成一段文字描述。这个能力只能从 Python API 开启：给构造函数传llm_client和llm_model，目前对 PPTX 和图片文件生效。

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("example.jpg").text_content)

仓库自带一张测试图 test_llm.jpg，就是给视觉模型做输入的样本：

不想全装：依赖分组与插件机制

[all]只是最省事的装法。pyproject.toml里每个可选依赖都是一个 extras 分组：pdf、docx、xlsx、xls、pptx、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding等。只处理 PDF 和 Word 的话：

pip install 'markitdown[pdf,docx]'

装得更快，占的空间也更小。插件机制则是另一条扩展通道，默认关闭：CLI 加--use-plugins，Python 侧传enable_plugins=True启用；markitdown --list-plugins查看已装插件。markitdown-ocr就是靠这套机制接进来的。

实战：把一个混合格式的资料目录变成 LLM 可用的语料

假设papers/目录里混着 PDF 论文、Word 报告和 Excel 数据表。输入是这些原始文件，MarkItDown 按扩展名逐个路由到对应转换器，输出是papers_md/里一一对应的.md。之后切片、建索引，面对的都只有一种格式：

for f in papers/*; do markitdown "$f" -o "papers_md/$(basename "${f%.*}").md" done

目录里有扫描件的话，装上markitdown-ocr、走 Python API 传llm_client，图片里的文字这一环就补齐了。

⚠️ 先绕开这三个坑

1. 冷门格式的依赖别全装。现象：转某个格式时报模块缺失。原因：该格式对应的 extras 没装。规避：按需pip install 'markitdown[<分组>]'，报错时先对照pyproject.toml里的分组名检查，而不是盲目[all]。

2. OCR 插件文档里的 CLI 参数与源码不一致。现象：照markitdown-ocr文档敲--llm-client openai，argparse 报未识别参数，LLM 没生效。原因：当前 CLI 源码__main__.py里并未注册这些参数。规避：以源码为准，用 Python API 传llm_client与llm_model。

3. 输出面向机器读，输入要区分信任边界。现象：复杂多栏、公式密集的文档转出来结构发乱。原因：输出定位是给文本分析工具消费，不是排版成品。规避：重要交付前人工抽查；处理不可信输入时用convert_local()代替convert()，后者会接受远程 URI。

一句话适用场景：手上有一批异构文档，要变成 LLM 能直接引用的语料。现在就装依赖，挑手边任意一个 PDF 跑一遍markitdown report.pdf -o report.md。

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