MarkItDown 快速上手：一条命令把办公文档转成 Markdown-开发者社区

MarkItDown 快速上手：一条命令把办公文档转成 Markdown

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

MarkItDown 是微软开源的轻量级 Python 工具，解决的是 LLM 语料准备阶段的文档转换问题：把 PDF、Word、Excel、PPT、图片、音频、HTML 等格式统一转成带结构的 Markdown，供下游的文本分析和检索流水线直接使用。如果你的工作流里需要把异构文档喂给大模型，又希望转换逻辑简单可控，它是一个很省心的起点。它面向的是"机器读"而不是"排版好看"，定位这一点决定了下面大部分行为。

先判断你该不该用它

适合选它的情况：

你要把一批文档变成 LLM 可消费的文本，输出带层级、表格、链接的 Markdown 比纯文本更省 token；
文档来源混杂（PDF、DOCX、XLSX、HTML 等），希望按扩展名自动路由到对应解析器，不用自己写分发逻辑；
你接受"机器可读"的质量标准，愿意对复杂排版文档抽查结果。

不适合的情况：

你要高保真还原文档版式（多栏、公式密集、精细排版）用于最终交付，官方明确说输出是给人勉强能看、给工具最合适的程度；
你处理的是不可控的第三方输入且又没做输入校验，它的 I/O 权限跟随当前进程，这点在安全要求高的服务端要特别注意（见文末）。

最小上手路径

环境要求 Python 3.10 至 3.14，建议先建虚拟环境。最短路径两条命令：

pip install 'markitdown[all]' markitdown path-to-file.pdf -o document.md

想验证第一次转换是否成功，可以不用-o，直接看标准输出：

cat path-to-file.pdf | markitdown

管道输入时如果文件没有扩展名线索，还能用-x参数提示格式（如-x pdf）。不需要全部格式的话，按 extras 装依赖更省体积，例如pip install 'markitdown[pdf,docx]'。

核心能力拆解

格式覆盖：十几种输入自动分流

每种格式对应一个独立转换器，源码集中在 converters/ 目录下，比如_docx_converter.py、_pdf_converter.py、_xlsx_converter.py。覆盖 PDF、PowerPoint、Word、Excel（含旧版 XLS）、图片（EXIF 与 OCR）、音频（转写）、HTML、CSV/JSON/XML、ZIP、EPUB、YouTube 链接等。你调用时完全不感知这个拆分，扩展名决定路由。

结构保留：输出是带骨架的 Markdown

痛点：纯文本转换会把标题层级、列表、表格全部压平，下游解析要靠猜。MarkItDown 保留标题层级、列表、表格、超链接，输出仍然是一份"有骨架"的文档。对切片喂 LLM 或建索引的场景，这比裸文本省 token 也更好读。

扩展能力：LLM 补图片，插件补 OCR

图片描述（仅 Python API 可用）：构造函数传入llm_client和llm_model，图片文件与 PPTX 中的图会在输出里带上一段视觉模型生成的描述。
第三方插件：默认关闭，用markitdown --list-plugins查看已安装插件，--use-plugins开启。官方仓库里的markitdown-ocr插件把 PDF/DOCX/PPTX/XLSX 内嵌图片交给视觉模型提取文字，扫描件 PDF（整页无文本）会以 300 DPI 渲染成整页图片送模型，提取结果包在*[Image OCR]...[End OCR]*标记里插回原文位置。

进阶场景：批量转换一个混合目录

假设papers/里混着 PDF 论文、Word 报告和 Excel 表格，目标是让每个文件都有对应.md：

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

输入是任意数量的混合格式文件，处理时按扩展名自动选转换器，输出是一个papers_md/目录。之后无论是切片、建索引还是直接问答，你面对的只有 Markdown 一种格式。目录里若含扫描件，装上markitdown-ocr并在 Python 侧传llm_client即可补齐图片文字。

边界、限制与常见坑

CLI 没有 LLM 参数：markitdown-ocr的 README 里出现过--llm-client写法，但当前 CLI 源码（__main__.py）并未注册这些参数，只有 Python API 能传llm_client。照插件文档敲命令行会发现 LLM 没生效，以源码为准。
不传llm_client时 OCR 静默跳过：插件照常加载，但会回退到内置转换器，不会报错，排查时容易误以为没装成功。
输出质量边界：面向文本分析工具，复杂排版（多栏、公式密集）转换后建议人工抽查，别直接当最终交付物。
不可信输入：官方建议服务端处理外部输入时做校验，并优先调用最窄的 API——只读本地文件用convert_local()，需要精细控制用convert_stream()，而不是能接受远程 URI 的convert()。
按格式装依赖排障：某类格式转换报错时，先确认对应 extras 是否装了对应依赖组。