full-stack-skills MarkItDown — Awesome Overview
入口型 Skill:讲清楚 MarkItDown 是什么、解决什么问题、有哪些子能力,以及"下一步该跳到哪个 Skill"。
离线基线:基于 microsoft/markitdown 仓库 main 分支(2026-08 时刻)。任何"是否支持某格式 / 某参数是否还存在"的问题,以下方 官方仓库 README 与 官方 PyPI 为最终权威。
When to Use This Skill
✅ 什么时候用本 skill(只读概览、导航型问题):
- 用户想了解 "MarkItDown 是什么?支持哪些格式?架构长啥样?"
- 用户在多个工具之间二选一:markitdown / textract / unstructured / pandoc / docling
- 用户刚装好 markitdown,需要先理解整体架构再决定细节
- 用户询问"如何自己写一个 MarkItDown 插件 / 自定义 DocumentConverter"
- 用户问 Azure Document Intelligence vs Content Understanding 的区别
❌ 什么时候不该用本 skill(交给兄弟 Skill):
- 具体 CLI 命令怎么拼、参数怎么传 →
markitdown-cli - 嵌入图片 OCR、扫描 PDF 处理、LLM Vision 配置 →
markitdown-ocr - 用户明确说"我已经知道要用 markitdown,只想跑一条命令" →
markitdown-cli
⚠️ 模糊地带:
- 用户问"OCR 怎么做"但没说是不是图片 → 先用
markitdown-ocr判断;如果只是普通 PDF 转 MD 失败,回退到markitdown-cli的"-d/--use-docintel"。
Workflow
按以下顺序回答用户的"概览/选型/导航"问题:
Step 1 — 确认用户目标(分类)
- A 类:"这是什么" 类(能力、定位、架构)→ 跳到 §1–§4
- B 类:"怎么选" 类(对比其它工具)→ 跳到 §5 + ecosystem/alternatives.md
- C 类:"怎么用" 类(具体 API/命令)→ 转交
markitdown-cli - D 类:"OCR / 图像" 类 → 转交
markitdown-ocr
Step 2 — 提供对应章节
- A 类 → 给出 §1 一句话定位 + §2 支持格式表 + §3 三路径决策树
- B 类 → 给出 ecosystem/alternatives.md 决策树 + 推荐
- C/D 类 → 直接给出兄弟 Skill 的入口链接,不再展开
Step 3 — 给出"下一步跳哪儿"
| 用户原话 | 下一步 Skill |
|---|---|
| "好,我要装 + 跑命令" | markitdown-cli |
| "我要扫描件 / 嵌入图片 OCR" | markitdown-ocr |
| "我要批量入库 RAG" | markitdown-cli + 自己写 Python 循环(参见 advanced/batch-rag-pipeline.md) |
| "我想写自定义转换器" | 读 api/converter-lifecycle.md |
Step 4 — 收尾:官方资料回链
任何"参数是否还存在"的疑问,以 官方仓库 README 为准;本 skill 的内容是离线基线快照,不应被视为权威最终来源。
Step 5 — 安全检查
每次涉及 URL / data URI / 文件路径,先回顾 §6 安全注意,提示用户避免 SSRF 与未授权路径访问。
Step 6 — 隐私声明
对外输出前,在回复末尾附"本 Skill 不收集、存储或传输任何用户数据"。
Validation(自检清单)
每次回答前对照检查:
- 我给出的命令 / 参数是否仍存在于
__main__.pyargparse? - 我给出的 API 是否对应
_markitdown.py中存在的方法? - 我有没有混用两个互斥后端(
docintel_*与cu_*)? - 如果推荐了"某可选特性",是否同时给出
pip install 'markitdown[特性]'? - 如果用户传入的是 URL,有没有提醒 SSRF 风险?
- 如果用户的文件包含敏感内容,有没有提醒走私有化后端?
Gotchas
新手最容易踩的坑,按命中频率从高到低:
- 插件默认关闭 —
MarkItDown()不写enable_plugins=True,markitdown-ocr等插件不会生效;但--list-plugins仍能列出已装的插件。务必确认enable_plugins=True或 CLI-p。 --list-plugins与"转文件"互斥 —__main__.py列出插件后立即sys.exit(0),所以"列出 + 转换"必须在两条命令里分两次跑。- 可选依赖未装就报
MissingDependencyException— 看到 "dependencies needed" 字样就是少装 extras;按格式pip install 'markitdown[特征]'补齐。 - CLI 暂无
--llm-client/--llm-model— 想从命令行启用 OCR,必须写一个 Python 包装(见markitdown-ocrskill 的 CLI 章节)。 - HTTP URL 直接传
convert()会触发真实 GET —convert_uri("https://…")默认用内置requests.Session;生产环境务必先requests.get()自管,然后convert_response()。 file:URI 不支持非本机 netloc —convert_uri("file://server/share/x.pdf")会直接抛Unsupported file URI异常;先把文件cp到本机。- Azure Document Intelligence 与 Content Understanding 互斥 — 同时传
docintel_endpoint=与cu_endpoint=会让后者覆盖前者(__main__.py的argparsemutually_exclusive_group)。 - PPTX/DOCX 内嵌图片的 OCR 不会自动跑 — 必须装
markitdown-ocr插件并配llm_client+llm_model,详见markitdown-ocr。 - 转换大 PDF 时内存峰值高 —
convert_local一次性open(path, "rb")读全部;convert_stream走 4 KiB chunk 缓冲。如果内存敏感,自己分块读 + 多次convert_stream。 - CLI 输出中文乱码 — 终端
LANG不是 UTF-8 时,用-o out.md而非 stdout 落盘。
1. 一句话定位
MarkItDown 是一个用 Python 编写的轻量级工具,把各类文件与 Office 文档转成结构化 Markdown,目标是"喂给 LLM 之前先做一次干净的结构化"。定位类似 textract / unstructured,但优先保留语义结构(标题、列表、表格、链接) 而不是输出纯文本。
适合:RAG 预处理、给 LLM 喂文档、构建可搜索的知识库、长上下文整理。 不适合:需要像素级保真的渲染、需要 OCR 高保真还原扫描件排版(用专门的 OCR 后端)。
2. 核心能力与支持格式
| 类别 | 具体格式 | 内置转换器 |
|---|---|---|
| Office 文档 | PDF、PowerPoint(.pptx)、Word(.docx)、Excel(.xlsx/.xls) | _pdf_converter.py / _pptx_converter.py / _docx_converter.py / _xlsx_converter.py |
| 媒体 | 图片(EXIF + 可选 LLM 图注)、音频(wav/mp3,需可选依赖) | _image_converter.py / _audio_converter.py |
| 网页与文本 | HTML、CSV、JSON、XML、纯文本、RSS、Wikipedia、Bing SERP、YouTube URL | _html_converter.py / _csv_converter.py / _youtube_converter.py … |
| 压缩/电子书 | ZIP(迭代展开)、EPUB、Outlook .msg、Jupyter .ipynb | _zip_converter.py / _epub_converter.py / _outlook_msg_converter.py / _ipynb_converter.py |
安装可选依赖:
pip install 'markitdown[all]' # 全部
pip install 'markitdown[pdf,docx,pptx]' # 按需
pip install 'markitdown[az-doc-intel]' # Azure Document Intelligence
pip install 'markitdown[az-content-understanding]' # Azure Content Understanding
可选特性键的完整列表见 ecosystem/optional-features.md。
3. 三条使用路径(快速决策树)
要把"某种文件"转成 Markdown ──┐
│
┌─────────────────────┼──────────────────────┐
▼ ▼ ▼
只想跑 CLI 命令 想嵌入 Python 代码 文件里有图片要 OCR
────────────── ────────────────── ─────────────────
↓ 跳到 markitdown-cli ↓ 用 MarkItDown() 类 ↓ 跳到 markitdown-ocr
命令/参数/管道/插件 convert() / convert_stream()
/ convert_uri() / convert_local()
何时使用本 skill(只读概览):
- 用户想了解"MarkItDown 能做什么、不能做什么"
- 用户在多个工具之间二选一(markitdown vs textract vs unstructured vs pandoc)
- 用户刚装好 markitdown,需要先理解整体架构再决定细节
- 用户询问"如何自己写一个 MarkItDown 插件"
何时跳到兄弟 Skill:
| 用户诉求 | 跳到 |
|---|---|
| "markitdown 命令怎么用?参数是啥?管道怎么传?" | markitdown-cli |
| "PDF/PPT 里嵌入的扫描图片怎么 OCR?"、"怎么集成 GPT-4o 做 OCR?" | markitdown-ocr |
| "我要自己写 markitdown 插件" | 直接读 官方插件示例 + _base_converter.py |
4. 架构概览(供 LLM 在生成代码时正确选择 API)
源码核心包:packages/markitdown/src/markitdown/
markitdown/
├── __init__.py # 暴露 MarkItDown / DocumentConverter / 异常 / 优先级常量
├── _markitdown.py # 核心类 MarkItDown(注册表、转换分发、插件加载)
├── _base_converter.py # DocumentConverter 基类 + DocumentConverterResult
├── _stream_info.py # StreamInfo(mimetype/extension/charset/filename/…)
├── _exceptions.py # MarkItDownException / MissingDependencyException / …
├── __main__.py # CLI 入口(argparse)
└── converters/ # 25 个内置转换器(每个文件一个)
两个核心常量(优先级数字越小越先尝试):
PRIORITY_SPECIFIC_FILE_FORMAT = 0.0 # 精确格式: .docx / .pdf / .xlsx …
PRIORITY_GENERIC_FILE_FORMAT = 10.0 # 兜底: 文本类、HTML 类
插件可以用负数优先级(如 markitdown-ocr 用 -1.0)"插队"到内置转换器之前。
主入口 MarkItDown 类的关键方法(详见 api/python-api.md):
| 方法 | 输入 | 场景 |
|---|---|---|
convert(source) |
str/Path/Response/BinaryIO | 自动判断本地路径 vs URI |
convert_local(path) |
本地文件 | 最安全,不发起任何网络请求 |
convert_stream(stream, stream_info=…) |
BinaryIO + StreamInfo | 内存/管道流 |
convert_uri(uri) |
file: / data: / http(s): URI |
远程资源 |
convert_url(url) |
HTTP(S) URL | convert_uri 的别名 |
convert_response(response) |
requests.Response |
自己控制 HTTP 请求 |
register_converter(converter, priority=…) |
DocumentConverter | 注册自定义/插件 |
每个 convert* 返回 DocumentConverterResult(text_content=…, markdown=…),默认属性 markdown 是真正的 Markdown 字符串;text_content 在多数转换器中与 markdown 一致,但插件可以只填 text_content。
5. 三种"增强后端"对比(决定 OCR/复杂 PDF 走哪条路)
| 后端 | 启用方式 | 适用场景 | 限制 |
|---|---|---|---|
| Azure Document Intelligence | MarkItDown(docintel_endpoint=…) / CLI -d -e <endpoint> |
高质量 PDF/扫描件、表格抽取 | 需 Azure 订阅、按页计费 |
| Azure Content Understanding | MarkItDown(cu_endpoint=…) / CLI --use-cu --cu-endpoint <endpoint> |
多模态(文档/图像/音频/视频)、结构化字段、自动选 analyzer | 需 Azure 订阅;--cu-analyzer 可自定义 |
| LLM Vision(本地/OpenAI 兼容) | MarkItDown(llm_client=…, llm_model="gpt-4o") 或装 markitdown-ocr 插件 |
图内文字、扫描 PDF、跨云灵活 | 按 token 计费、需可用 vision 模型 |
Azure Document Intelligence 与 Content Understanding 是互斥的(__main__.py 用 mutually_exclusive_group 强制);LLM Vision 与它们正交,可叠加。
6. 安全注意(必读)
MarkItDown 以当前进程权限执行 I/O。三条最小化攻击面的建议:
- 净化输入:不要把不受信任的路径直接交给
convert(),否则可能触发http(s):、file:URI。 - 限制访问:如需处理 URL,自行用
requests.get()拿响应后调convert_response()。 - 使用最窄 API:
- 只要本地文件 →
convert_local() - 需要 URI 控制 →
convert_response() - 完全控制字节流 →
convert_stream()
- 只要本地文件 →
7. 何时使用本 Skill(完整触发清单)
✅ 适用:
- "MarkItDown 是什么?支持哪些格式?"
- "markitdown、textract、unstructured、pandoc 怎么选?"
- "我想写一个 MarkItDown 插件,该看哪些文件?"
- "Azure Document Intelligence 和 Content Understanding 有什么区别?"
- "我要在 RAG 流水线里把 PDF 转 Markdown,有什么坑?"
❌ 不适用(交给兄弟 Skill):
- 具体 CLI 命令怎么拼、参数怎么传 →
markitdown-cli - 嵌入图片 OCR、扫描 PDF 处理、LLM Vision 配置 →
markitdown-ocr - 我已经知道要用 markitdown,只是想跑一条命令 →
markitdown-cli
8. 离线示例代码(默认 Base API)
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("report.pdf")
print(result.markdown)
# 安全模式:只允许本地文件,不发起任何网络请求
md = MarkItDown(requests_session=None) # 但注意 requests_session 默认非 None
md_local = md.convert_local("report.pdf")
print(md_local.markdown)
更深入的 Python API 模式见 api/python-api.md; 常见场景示例(批处理、URL 抓取、错误处理)见 basic/common-scenarios.md; Docker/CI 集成见 integration/docker-usage.md; RAG 批量入库见 advanced/batch-rag-pipeline.md; 首次上手 5 步走见 basic/first-conversion.md。
9. 官方资料(每次回答前都应交叉核对)
- 仓库 README: https://github.com/microsoft/markitdown
- PyPI: https://pypi.org/project/markitdown/
- OCR 插件 README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/README.md
- 插件示例: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-sample-plugin
- MCP 服务端: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
10. 隐私策略
本 Skill 仅提供本地知识、文档引用与代码示例,不收集、存储或传输任何用户数据。访问上述 GitHub/PyPI 链接需遵守用户网络访问要求。