MarkItDown:把文档先变成 Markdown,再交给模型
结论
MarkItDown 不负责理解内容,只负责把各种文档转成模型容易读的 Markdown。它保留标题、列表、链接和表格结构,比直接塞二进制或整页 HTML 干净;但转换结果不是免费的,复杂版式总会丢信息。
它解决什么问题
把 PDF、Word、Excel、PPT 或网页交给模型时,原始格式既占 token 又难解析:PDF 的排版信息对模型没有意义,HTML 里还混着导航和脚本。MarkItDown 统一转成 Markdown,附带工具和 MCP 服务器,适合做 RAG 入库前的预处理,也适合把网页正文摘出来。它输出的是结构,不是摘要,因此后续仍要自己决定哪些内容进上下文。
我的实验
先取当前站点渲染后的 HTML,再用 uvx markitdown 转换:
curl -s http://localhost:3000/ -o page.html
uvx markitdown page.html
源文件 22,702 字节,输出保留了「组件与 tokens」标题、导航链接、## 主题偏好 等二级标题,以及颜色 token 的代码格式,没有把整页塞成一段纯文本。uvx 在临时环境里运行,不必把转换依赖装进项目。
限制
- 只处理已经拿到的内容。依赖 JavaScript 渲染的页面要先抓渲染后的 HTML,否则只能得到空壳。
- 扫描版 PDF 需要 OCR;图片里的信息不会自动变成可靠文本。
- 复杂表格、双栏排版和公式可能被压平或错位,重要内容要抽查。
- 不同格式依赖不同的可选组件,安装时按需引入,不要默认全量。
- 转换质量取决于源文件,不能把输出当成原文的完整等价物。
适合谁
要把文档、网页或报告整理成 RAG 语料的人。只是读一两段文字时,直接复制更快。