跳到主要内容
Ed. notes

MarkItDown:把文档先变成 Markdown,再交给模型

工具 · 2026-11-10

  • 文档转换
  • 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 语料的人。只是读一两段文字时,直接复制更快。

继续探索