to-markdown

转换为 Markdown

使用 MarkItDown 作为转换引擎，并通过轻量级 URL 抓取层，将任意文件或 URL 转换为整洁的 Markdown。

参考文件

文件	用途
references/formats.md	各格式的处理说明、内部引擎和已知缺陷
references/fetch.md	URL 抓取层：trafilatura + Playwright 策略
references/install.md	所有变体的依赖项安装指南

决策树

在使用任何工具前，先确定输入类型：

Input type?
  Local file path        -> markitdown directly
  URL
    YouTube URL          -> markitdown directly (transcript extraction built-in)
    Static page          -> trafilatura fetch -> markitdown on HTML result
    JS-rendered / auth   -> Playwright fetch -> markitdown on result
  Pasted HTML string     -> markitdown directly on string

对于 URL，不要使用 web_fetch 或 WebFetch——应通过 references/fetch.md 中所述的抓取层处理，以保留转换流水线。

核心转换工作流

步骤 1：确保依赖项已就绪

uv pip show markitdown || uv pip install 'markitdown[all]' trafilatura

选择性安装和完整依赖项表请参阅 references/install.md。

步骤 2：转换

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("path/to/file.pdf")
print(result.text_content)

步骤 3：工作流

1. 检测输入类型（文件路径、URL、原始 HTML）。
2. 如果是 URL，先运行抓取层（参见 references/fetch.md）。
3. 对本地文件或抓取的内容运行 markitdown 转换。
4. 如有需要，进行后处理（移除冗余内容、裁剪至主要内容）。
5. 按照下方的输出约定写入或直接返回内容。

输出约定

场景	输出行为
单个文件，用户需要文件	将 <input_stem>.md 写入同一目录
单个文件，要求内联返回	在对话中返回 Markdown
批量（多个文件）	将每个文件写入 <stem>.md，并总结生成的内容
URL	将 <slug>.md 写入当前目录或内联返回
管道传入另一个工作流	仅返回 result.text_content 字符串

默认行为：“转换此文件” -> 写入文件。“读取这个”或“这上面写了什么” -> 内联返回。

输出示例

来源（包含表格的双栏 PDF）：

Annual Report 2024                    Financial Highlights
Revenue grew 12% year-over-year...    | Metric   | 2023  | 2024  |
                                      | Revenue  | $4.2B | $4.7B |
                                      | EBITDA   | $1.1B | $1.3B |

转换后的 Markdown：

# Annual Report 2024

Revenue grew 12% year-over-year...

## Financial Highlights

| Metric  | 2023  | 2024  |
| ------- | ----- | ----- |
| Revenue | $4.2B | $4.7B |
| EBITDA  | $1.1B | $1.3B |

多栏布局会合并为线性内容。表格会保留为 Markdown 表格。标题根据字体大小和粗细推断。

LLM 图像描述（可选启用）

Markitdown 支持使用 llm_client 为 PPTX 和图像文件生成图像描述。默认绝不启用——这会产生费用、增加延迟，并触发意外的 API 调用。请先询问用户：“此文件包含图像。您要我使用 Claude 描述这些图像吗？这会产生额外的 API 调用。”

import anthropic
from markitdown import MarkItDown

client = anthropic.Anthropic()
md = MarkItDown(llm_client=client, llm_model="claude-sonnet-4-6")
result = md.convert("presentation.pptx")

Opus 4.7 视觉能力上限： Opus 4.7 可处理长边最大为 2,576 像素（约 3.75 MP）的图像，比之前的 Claude 模型约高 3 倍。使用 llm_model="claude-opus-4-7" 处理图像较多的文档时，应保留更高分辨率的源图像，而不要提前降低分辨率——此前需要 OCR 才能识别的屏幕截图和图表中的文字，现在可能可以直接读取。

错误处理

严重性	条件	操作
终止	不支持的格式（不存在转换器）	立即告知用户；不要重试
终止	受密码保护的 Office 文件	告知用户；无法通过编程方式解决
终止	找不到文件／路径无效	报告确切路径；请用户核实
恢复	PDF 输出为空	可能是扫描件 — 转至 references/formats.md 中的 OCR 处理流程
恢复	缺少可选依赖项（例如 playwright）	安装依赖项，然后重试转换
恢复	URL 获取到付费墙页面	报告获取限制；不要重试或尝试绕过
恢复	trafilatura 返回空结果	按照 references/fetch.md 转至 Playwright 获取策略

result = md.convert(path)
if not result.text_content.strip():
    raise ValueError(f"No text extracted from {path}. See references/formats.md for OCR options.")

绝不要悄无声息地返回空 Markdown。请说明失败情况及其严重性，并指出相关参考文件。

已知缺陷与升级处理

• HTML 保真度：markitdown 内部使用 html2text — 复杂布局会丢失结构。对于需要保留 DOM 结构的高保真 HTML 转换，建议通过 Node 子进程使用 Turndown。
• 严格付费墙：获取层返回的是注册墙页面，而非内容。这是获取限制，不是转换问题。
• 扫描版 PDF（仅含图像，没有文本层）：markitdown 返回的输出几乎为空。请升级至 OCR 工作流（Azure Document Intelligence 或 Tesseract）。请参阅 references/formats.md。
• 受保护的 Office 文件：受密码保护的 DOCX/XLSX 转换会失败。请告知用户。

校准规则

1. 转换后的输出每页至少应包含源文档中的 10 个词。低于此阈值时，应视为空提取，并按照错误处理表升级处理。
2. 源文档中的表格必须在输出中呈现为 Markdown 表格 — 如果原文中存在表格但转换结果中缺失，请提醒用户。
3. 必须保留源文档的标题层级（H1 > H2 > H3）。结构化文档转换后没有标题的扁平输出，表明转换质量存在问题。
4. 转换 URL 时，输出不得包含导航元素、Cookie 横幅或页脚模板文本。如存在此类内容，请使用 include_tables=True 重新通过 trafilatura 处理，以去除模板文本。
5. 多工作表 XLSX 必须为每个工作表生成一个标注清晰的章节。缺少工作表表明转换不完整 — 请报告已提取的工作表。

限制

• 不绕过付费墙。记录这一限制，不要尝试绕过。
• 未内置 Turndown 集成。它使用不同的运行时（Node.js）。
• 不支持定时／批量爬取。每次调用只转换一个文件。
• 输出格式仅限 Markdown。
• 自动生成的 YouTube 字幕可能会包含技术术语错误。
• 扫描版 PDF 需要外部 OCR — 单独使用 markitdown 会返回空输出。