让文档对 AI agents 友好的 Markdown 写法

最近如果你关注过开发者圈的 Twitter，可能已经看到 Bun 发的那条推文：向 Claude Code 等 AI 编程助手直接提供 Markdown 内容。

Mintlify 和 Fumadocs 都迅速在自己的文档平台中实现了这一功能，我最近也为 Lingo.dev 完成了相同的实现。

下面我们来看看它为什么重要，以及如何自己实现这一功能。

问题：HTML 臃肿

AI Agent 可以获取网页内容，为开发者提供帮助。大多数情况下，获取到的内容都是 HTML。但 HTML 包含大量标记，这些标记会消耗 token，却无法提供有意义的信息，最终导致性能下降。

解决方案：内容协商

一个优雅的解决方案是内容协商（Content Negotiation）。这是标准的 HTTP 机制，客户端可以通过 Accept header 告诉服务器自己希望接收哪种格式。

当 AI Agent 使用 Accept: text/markdown 或 Accept: text/plain 请求你的文档时，服务器可以返回 Markdown，而不是 HTML。

• 使用更少的 token 传递同样的信息
• 更容易解析和理解
• context window 能够容纳更多文档内容

具体实现细节取决于你使用的编程语言和框架，但整体思路是一致的。

下面以 Express.js 为例，一步步介绍如何实现。

1. 检测 Accept header

请求到达时，检查 Accept header 是否包含 text/markdown 或 text/plain：

app.get("/docs/*", (req, res) => {
  const acceptHeader = req.headers.accept || "";

  if (acceptHeader.includes("text/markdown")) {
    // Serve Markdown
  } else if (acceptHeader.includes("text/plain")) {
    // Serve plain text
  } else {
    // Serve HTML (default behavior)
  }
});

2. 提供原始 Markdown

加载并返回所请求页面的原始 Markdown 内容：

if (acceptHeader.includes("text/markdown")) {
  const markdownContent = await loadMarkdownForPage(req.path);
  res.setHeader("Content-Type", "text/markdown; charset=utf-8");
  res.send(markdownContent);
  return;
}

3. 回退到现有行为

对于其他所有请求（浏览器、爬虫等），继续使用现有的 HTML 渲染逻辑：

res.render("docs", { content: processedContent });

4. 测试你的实现

使用 curl 验证实现是否正常工作：

# Request Markdown
curl -H 'Accept: text/markdown' https://lingo.dev/en/cli

# Request plain text
curl -H 'Accept: text/plain' https://lingo.dev/en/cli

# Request HTML (default)
curl -H 'Accept: text/html' https://lingo.dev/en/cli

对于 Markdown 请求，你应该看到：

• Response header：Content-Type: text/markdown; charset=utf-8
• Body：不包含 HTML 标签的原始 Markdown 内容

对于 HTML 请求，你应该看到正常渲染后的页面。

延伸阅读与资源

如果想进一步了解如何实现这一功能，可以查看以下资源：

• Accept header 文档
• @cramforce 提供的 Next.js 模板
• @retlehs 提供的 Laravel 配置指南
• @skeptrune 提供的静态网站、Cloudflare Workers 和 Caddy 配置指南

（如果你编写了自己的指南、示例或模板，欢迎分享到评论区，我可以将它添加到文章中。）

部分评论可能仅对已登录的访客可见。登录后即可查看全部评论。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。