markitdown

markitdown

使用 Microsoft 的 markitdown 将文档转换为整洁的 Markdown。 它会保留结构——标题、表格、列表、链接、幻灯片备注、工作表名称——而不是抓取成一整段文本，因此很适合作为大模型的输入。

它会提取文件中已有的文本。它不会进行 OCR：扫描版 PDF 和照片的转换结果为空（见下文“仅含图像的内容”）。

设置

markitdown --version   # expect 0.1.x or later

如果未安装，请将其作为隔离工具安装。它需要 Python 3.10+：

uv tool install "markitdown[all]"      # preferred
pipx install "markitdown[all]"         # alternative

不要在 macOS 系统 Python（3.9）上直接运行 pip install：pip 会悄悄解析到古老的 markitdown 0.0.1a1，它没有 [all] 扩展，也没有可用的 CLI。如果安装报告中出现 0.0.1a1 或“does not provide the extra 'all'”，说明解释器版本太旧——请使用 uv tool install 或 uv venv -p 3.12。

[all] 会安装所有可选转换器。精简安装可以选择额外组件：pdf、docx、pptx、xlsx、xls、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding。MissingDependencyException 会指出缺少的额外组件。

如果环境禁止全局安装，请使用临时 venv，并直接调用 <venv>/bin/markitdown。

单个文件

markitdown report.pdf -o report.md      # write to a file
markitdown report.pdf                    # stdout — good for piping into a prompt
curl -sL "$URL" | markitdown -x html     # stdin: add -x/-m hints for reliable detection

实用标志（完整列表：markitdown --help）：

标志	用途
-o FILE	输出到文件，而不是 stdout
-x EXT / -m MIME / -c CHARSET	格式提示——主要用于 stdin
--keep-data-uris	保留内联 base64 图像（默认会截断）
-p / --list-plugins	使用 / 列出已安装的第三方插件
-d -e URL	Azure Document Intelligence（云端 OCR）——参见参考资料
--use-cu --cu-endpoint URL	Azure Content Understanding——参见参考资料

文件缺失和格式不受支持时，退出状态为非零；但仅含图像的内容即使输出为空，退出状态也会是 0——因此务必检查结果是否为空白。

批量转换

转换目录时，请使用随附脚本，而不是自己编写循环：

bash <skill-dir>/scripts/batch_convert.sh SRC_DIR [OUT_DIR]
# MARKITDOWN=/path/to/markitdown   if it isn't on PATH
# EXTENSIONS="pdf docx"             to narrow the file types

它会递归处理，将目录树映射到 OUT_DIR（或将文件写在各自的源文件旁），并将输出命名为 <file>.<ext>.md，以避免 report.pdf 和 report.docx 发生冲突；重新运行时会跳过已是最新的输出，最后还会生成摘要，标出 EMPTY（需要 OCR）、FAILED（附带错误）和 LEGACY（.doc/.ppt）文件。请将这些标记的文件反馈给用户——这些文件需要进一步决定如何处理。如果用户想采用不同的命名方案（例如 report.md），请修改脚本中的 dest= 行，而不是重写脚本。

哪些格式转换效果好

输入	结果
.docx	标题、列表、表格、链接——如果表格的第一行未标记为 Word 标题行，就会生成一个空的 | | | 表头，实际表头则成为第一行数据；如果表格很重要，请手动修正
.pptx	每张幻灯片对应一个章节（``），演讲者备注位于 ### Notes: 下方
.xlsx / .xls	每个工作表对应一个 ## SheetName 章节和一张表格
PDF（数字版）	文本和通过 pdfplumber 还原的表格；复杂的多列布局可能会错乱
HTML、RSS/Atom、Wikipedia、Bing 结果	主要内容为 Markdown
CSV / JSON / XML / .ipynb	表格 / 文本 / notebook 单元格
EPUB、Outlook .msg	章节 / 标题和正文
ZIP	每个受支持的文件成员，分别置于 ## File: name 下
音频（.wav .mp3 .m4a .mp4）	元数据和通过 Google 免费 Web Speech API 生成的转录文本——会上传音频，需要网络
YouTube URL	标题、说明，以及可用时的转录文本
图像（.jpg .png）	仅 EXIF 元数据（需要 exiftool）和可选的大模型图注——不进行 OCR

不支持旧版 .doc / .ppt（UnsupportedFormatException）。请先转换： 在 macOS 上运行 textutil -convert docx memo.doc，或者使用 LibreOffice 运行 soffice --headless --convert-to docx memo.doc，然后再运行 markitdown。

纯图像内容（扫描件、照片）

当 PDF 或图像转换后输出为空或几乎为空时，文字是像素，而不是字符。请直接告知用户，然后选择一种方式：

1. 自行读取。 如果你能查看图像和 PDF（例如使用 Read 工具），请打开文件并转录内容——对于少量页面，这通常是最快的方式。说明这是你转录的内容，而不是 markitdown 的输出。
2. 本地 OCR，如果已安装：对 PDF 执行 ocrmypdf scan.pdf out.pdf，然后用 markitdown 处理 out.pdf；图像则执行 tesseract scan.png - 。
3. 云端 OCR：Azure Document Intelligence（-d -e ...）——会将文档发送到 Azure；只有在获得用户同意后才能使用。

切勿把空的 .md 文件当作转换成功的结果交给用户。

Python API

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.pdf")   # path, URL, or binary file-like object
text = result.markdown              # the Markdown string (alias: .text_content)
title = result.title                # may be None

有关流、错误处理、大模型图像说明、Azure 和插件的信息，请阅读 references/python-api.md。

交付结果前

• 查看输出。 使用 head 查看或直接阅读。检查表格是否正常显示、文本是否乱码或为空；如果有这些情况，请告知用户。
• 隐私。 离线转换会在本地进行；音频转录、YouTube、大模型说明和 Azure 会将内容发送到外部。使用这些方式处理敏感文件前，请先征求用户同意；密钥（OPENAI_API_KEY、Azure 凭据）应保存在环境中，切勿写入代码。
• 大型输出。 较长的 PDF 可能生成数 MB 的 Markdown。请写入文件，并阅读或 grep 所需部分，而不是将全部内容都输出到对话中。