MarkItDown CLI 完整使用指南

用途明确:让 LLM 能基于本 skill 生成正确、可复制粘贴的 markitdown 命令行调用。

离线基线:基于 markitdown 命令的 argparse(见 packages/markitdown/src/markitdown/__main__.py)。任何"该参数是否存在"的判断,以源码为准;遇到本文与官方 README 冲突时,以官方为准。

When to Use This Skill

✅ 什么时候用本 skill(纯 CLI / 命令行问题):

• 用户问 "markitdown 命令怎么用?有哪些参数?"
• 用户想批量转 PDF/PPT/Word → Markdown
• 用户想把 stdin 流(管道 / curl 输出)喂给 markitdown
• 用户问"怎么列出已装插件"、"怎么启用插件"
• 用户问 Azure Document Intelligence / Content Understanding 的 CLI 配法
• 用户问"CLI 怎么把输出写到文件而不是 stdout"

❌ 什么时候不该用本 skill:

• 想用 Python API → markitdown-awesome 的 references/api/python-api.md
• 想做 OCR(嵌入图片 / 扫描 PDF / LLM Vision)→ markitdown-ocr
• 想了解 MarkItDown 是什么、支持哪些格式 → markitdown-awesome
• 用户已经会 markitdown,只是问最佳实践 → 直接给示例,不绕到本 skill

⚠️ 模糊地带:

• 用户问"OCR 怎么做" → 默认走 markitdown-ocr(因为 CLI 当前不支持 LLM 参数)。
• 用户问"怎么转 PDF"但没说场景 → 默认 CLI 路径,但同时提示:若是扫描件,推荐 Azure DI。

Workflow

每次回答 CLI 类问题时,按下面流程走一遍:

Step 1 — 确认输入与输出

• 输入:<file> / stdin / http(s)://…?
• 输出:stdout / -o out.md / tee 复用?
• 是否有特殊格式需要提示(-x / -m)?

Step 2 — 选择后端(默认 / Azure DI / Azure CU)

• 默认(本地):不传 -d 也不传 --use-cu
• 高质量 PDF/扫描:-d -e <endpoint>
• 多模态/结构化字段:--use-cu --cu-endpoint <endpoint>

Step 3 — 选择是否启用插件

• OCR(LLM Vision)→ -p,但记得 CLI 没有 --llm-client/--llm-model,需要 Python 包装(见 markitdown-ocr)
• 自定义插件 → 同上,-p 即可

Step 4 — 组装命令并自检

对照 Validation 自检清单走一遍。

Step 5 — 处理错误

若用户给出 MissingDependencyException / UnsupportedFormatException 等异常,跳到 §8 排错速查。

Step 6 — 给下一步建议

输出命令后,补一句:"需要批量 / 集成 CI / Docker,看 examples/advanced/safe-batch-processing.md"。

Validation(自检清单)

每条命令生成后,过一遍:

• -d 与 --use-cu 没有同时出现?
• 用 -d 时必带 -e <endpoint>?
• 用 --use-cu 时必带 --cu-endpoint <endpoint>?
• 从 stdin 读但文件无扩展名 → 加了 -x 或 -m?
• 走 HTTP URL → 评估了 SSRF 风险?
• 输出含非 ASCII → 推荐 -o out.md 而非 stdout?
• 用户装了插件但没启用 → 提示加 -p?
• CLI 没有 --llm-client → 没误承诺能从命令行启用 OCR?
• --list-plugins 与"转文件"没在同一命令行?

Gotchas

按命中频率从高到低:

1. -d 与 --use-cu 互斥 — argparse 强制 mutually_exclusive_group,两条同时出现直接报错。
2. -d 必须配 -e — 否则 __main__.py 主动 _exit_with_error("Document Intelligence Endpoint is required …")。
3. --use-cu 必须配 --cu-endpoint — 同上逻辑。
4. CLI 没有 --llm-client / --llm-model — 想从命令行启用 OCR,必须用 Python 包装(详见 markitdown-ocr)。不要编一个不存在的 flag。
5. --list-plugins 触发即 sys.exit(0) — 与"转文件"在同一命令行组合时,转换逻辑根本不会跑。
6. 从 stdin 读时无扩展名 → 必须 -x 或 -m — 否则 accepts() 全 False,报 UnsupportedFormatException。
7. -c charset 用 codecs.lookup 校验 — 写错会 _exit_with_error("Invalid charset: …");常见可用值:utf-8、utf-16、latin-1、gbk(需在系统 codecs 注册)。
8. CLI 输出中文乱码 — 终端 LANG != *UTF-8 时,加 -o out.md 落盘。
9. --keep-data-uris 默认不保留 — 输出里 base64 图片会被截掉;若用户需要图,用 --keep-data-uris。
10. HTTP URL 走真实 GET — convert_uri 内部会发请求;SSRF 风险由调用方承担。生产建议用 Python requests.get() + convert_response()。
11. 大文件内存峰 — convert_local 一次性 open(path, "rb"),几百 MB 的 PDF 内存可能爆。流式场景用 convert_stream。
12. 缺可选依赖 — 报 MissingDependencyException 时,按格式 pip install 'markitdown[<extra>]' 补,不要省略方括号。
13. Azure 凭据 — DI/CU 默认走默认凭据链;CLI 里没有显式传 key 的选项,凭据由环境/SDK 决定。
14. --cu-file-types 接受逗号分隔字符串 — 写错类型名会 _exit_with_error("Unknown file type: …"),与 ContentUnderstandingFileType 枚举对齐。
15. 管道断裂会导致 BrokenPipeError — 用 markitdown f.pdf | head 时,MarkItDown 会写完整个 markdown 后 print 触发 EPIPE;不影响结果,但 head 退出码非零会让 set -o pipefail 失败。

1. 最简形态

markitdown <file>            # 转 stdout
markitdown <file> -o out.md  # 写文件
cat <file> | markitdown      # 从 stdin 读
markitdown < <file>          # 等价写法

<file> 可以省略:省略时强制从 stdin 读取。 注意:走 stdin 时,MarkItDown 不知道真实扩展名,需要用 -x 或 -m 提示。

2. 完整参数清单

互斥组:-d(--use-docintel)与 --use-cu 互斥,只能选一个。

3. 输入/输出矩阵

CLI 目前没有 -i/--input 参数,只能靠 stdin 或 <file> 占位。

4. 输出控制

• stdout 编码容错:_handle_output() 会用 sys.stdout.encoding + errors="replace" 写,不会因为终端编码崩溃。
• 超大输出:MarkItDown 默认一次性 print(result.markdown),不要把它丢到日志文件里。建议加 -o。
• 图片 data URI:--keep-data-uris 控制是否在输出 Markdown 中保留 data:image/...;base64,…(默认会被截掉以减小体积)。

5. 插件管理

# 看装了哪些插件
markitdown --list-plugins
# 输出类似:
# Installed MarkItDown 3rd-party Plugins:
#   * ocr              (package: markitdown_ocr)
#   * my-plugin        (package: my_pkg)
# 若没有:打印 "  * No 3rd-party plugins installed."

# 启用插件
markitdown scanned.pdf -p
# 加 LLM 参数配合 markitdown-ocr:
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ markitdown --list-plugins 与 -p/--use-plugins 不冲突——但 __main__.py 中 --list-plugins 触发后立即 sys.exit(0),所以它和"转文件"不能在同一命令行组合。

5.1 通过环境变量配置 OpenAI 兼容客户端(配合 markitdown-ocr)

export OPENAI_API_KEY=sk-...
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ 注意:__main__.py 当前的 argparse 并未注册 --llm-client 与 --llm-model 选项(它们仅在 Python API MarkItDown(llm_client=…, llm_model=…) 中可用)。要通过 CLI 启用 OCR,目前最稳妥的方式是写一个 3 行 Python 包装(见 markitdown-ocr skill)。官方未来若加入 CLI 选项,优先遵循官方说明。

6. Azure 后端切换

6.1 Document Intelligence(-d -e)

markitdown scan.pdf -d -e "https://<resource>.cognitiveservices.azure.com/"

适用:高质量 PDF、扫描件、表格抽取。需要 pip install 'markitdown[az-doc-intel]',且环境需能访问该 endpoint(Azure 凭据走默认链)。

6.2 Content Understanding(--use-cu --cu-endpoint)

# 自动选 analyzer(按文件类型:documentSearch/videoSearch/audioSearch)
markitdown report.pdf --use-cu --cu-endpoint "https://<cu>.services.ai.azure.com/"

# 自定义 analyzer
markitdown invoice.pdf --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-analyzer "my-invoice-analyzer"

# 仅对部分类型启用 CU
markitdown mixed_files/ --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-file-types pdf,jpeg,mp4

适用:多模态(文档/图像/音频/视频)、需要结构化 YAML front matter、定制分析器。

完整对照(CLI ↔ Python API ↔ 服务端点)见 azure/endpoint-matrix.md;实战脚本见 examples/azure/azure-backends.md。

7. 典型工作流示例

7.1 批量把目录 PDF 转 Markdown

find ./inbox -name '*.pdf' -print0 | while IFS= read -r -d '' f; do
  out="./md/$(basename "${f%.pdf}").md"
  markitdown "$f" -o "$out"
done

7.2 配合 xargs 并行(谨慎使用)

find ./inbox -name '*.pdf' -print0 \
  | xargs -0 -n1 -P4 -I{} sh -c 'markitdown "{}" -o "./md/$(basename "{}" .pdf).md"'

⚠️ 部分 PDF 处理时占用大量内存与网络 IO,并行度不宜超过 CPU 数。

7.3 配 jq/grep 做后续过滤

# 把 PDF 转 Markdown,然后保留所有 "##" 开头的章节
markitdown report.pdf | grep -E '^##' > outline.md

7.4 把抓到的网页存为 Markdown

curl -sL "https://example.com/article.html" \
  | markitdown -m text/html \
  > article.md

7.5 Docker 一行命令

参考 Dockerfile(docker build -t markitdown:latest . 后):

docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
# 等价于:
docker run --rm -v "$PWD":/data markitdown:latest /data/your-file.pdf -o /data/output.md

更多批量 / CI / Docker 实战见 examples/advanced/workflows.md 与 examples/advanced/safe-batch-processing.md。

8. 排错速查

9. 安全注意

• MarkItDown 用当前进程权限做 I/O。不要把任意 URL 直接喂给 markitdown https://...,否则 SSRF 风险由调用方承担。
• 容器场景务必限定 --user 与 --read-only 卷挂载。

10. 何时跳到兄弟 Skill

11. 隐私策略

本 Skill 仅提供本地文档与示例,不收集、存储或传输任何用户数据。命令调用与 Azure endpoint 通信由用户在自己的环境中发起,隐私责任由用户承担。

12. 参考链接

• 官方 README
• 官方 argparse 源码
• Dockerfile
• 参数速记:本仓库内的 references/cli/cheatsheet.md
• 兄弟 Skill:markitdown-awesome — 用 npx skills add full-stack-skills/document-skills --skill markitdown-awesome 装好后按 skill 名引用
• 兄弟 Skill:markitdown-ocr — 用 npx skills add full-stack-skills/document-skills --skill markitdown-ocr 装好后按 skill 名引用
• 完整安装:npx skills add full-stack-skills/document-skills(一次性装齐全部 11 个 skill)