MarkItDown
MarkItDown 入门：转换一个文件，并检查结果是否可信
建立精简的 MarkItDown 环境，对照 CLI 与 Python API 的输出，区分依赖缺失和提取质量问题。
你将学会
- CLI 和 API 对照应使用同一份已知样本。
- 核验输出中的事实，而不只是退出状态。
- 插件配置可能改变选择过程，需要记录。
开始前需要
- 具备基础 Python 与命令行知识
- 准备一份内容可核验且不含敏感信息的文档
使用本章清单解释并验证文档导入流程中的对应环节。
先看结论
- CLI 和 API 对照应使用同一份已知样本。
- 核验输出中的事实，而不只是退出状态。
- 插件配置可能改变选择过程，需要记录。
围绕手头的文件安装依赖
文档要求 Python 3.10 或更新版本。建议使用虚拟环境，避免 PDF、Office 等可选依赖与其他应用发生隐蔽冲突。README 支持 pdf、docx、pptx 等单独的 extras，也提供安装全部可选依赖的方式。
第一次练习可以只安装 docx 依赖，并自行准备 example.docx。安装命令会解析执行当时可用的版本；试验成功后，先记录实际安装版本，再把环境交给团队复现。下方命令是操作说明，不代表本文已运行所有格式的转换器。
用同一个样本对照两种接口
CLI 接收输入路径，并通过 -o 指定输出路径。Python API 返回转换结果，其 markdown 属性包含生成的文本。两种接口应使用同一个文件，才能在不改变内容和依赖的前提下调查输出差异。
验收应检查具体事实：标题是否只出现一次、链接是否指向正确地址、表格数值是否仍对应原标签、特殊字符是否保留。把预期事实与样本一同保存。本次练习中，即使输出文件存在，内容为空仍应判定为失败。
把环境故障与内容问题分开排查
导入报错或可选依赖缺失属于环境问题；转换完成但表格缺失、阅读顺序混乱属于内容质量问题。修改依赖前，记录第一个异常和输入格式。一次性更换多种 extras 与插件，会使问题来源更难判断。
README 说明第三方插件默认关闭。启用前先列出已安装插件，再用相同样本重跑。插件可能改变转换器选择，因此应把插件配置与结果一起保存，不要把它当成不会影响行为的隐形增强。
实施步骤
- 1
创建并激活 Python 虚拟环境。
- 2
安装 docx 依赖并准备 example.docx。
- 3
使用 -o 转换文件，检查 Markdown。
- 4
记录依赖版本并与 API 输出对照。
可复制示例
python -m venv .venv
# POSIX 命令行；Windows 请使用虚拟环境的 PowerShell 激活脚本。
. .venv/bin/activate
python -m pip install "markitdown[docx]"
markitdown example.docx -o example.md
python -m pip freeze常见问题
需要一开始就安装全部依赖吗？
先安装实际需要的格式即可。all 适合广泛评估，但会引入更多依赖。
为什么启用插件后输出变了？
插件可以注册新的转换器及优先级。固定样本并记录配置，才能判断差异来源。