如何向 AI 代理提供 Markdown 文档：让你的文档更易于 AI 访问
介绍
如果你最近关注过开发者推特，你可能已经看到 Bun 发的推文，内容是关于将 Markdown 直接提供给 Claude Code 等 AI 编码助手。
Mintlify和Fumadocs都已在其文档平台中立即实现了该功能，而我自己也刚刚在Lingo.dev中实现了该功能。
这就是为什么它很重要，以及如何自己实施它。
问题：HTML 代码臃肿
人工智能代理可以获取网页内容以辅助开发者。大多数情况下，这些内容以 HTML 格式返回。但 HTML 中包含的标记会消耗令牌，却不添加任何有意义的信息，从而降低性能。
解决方案：内容谈判
优雅的解决方案是内容协商。这是一种标准的HTTP机制，客户端通过HTTP头部告诉服务器它们偏好的格式Accept。
当 AI 代理使用 `<html>`Accept: text/markdown或 `<html>`请求您的文档时Accept: text/plain，您的服务器可以返回 Markdown 而不是 HTML。
这意味着：
- 用更少的令牌传递相同的信息
- 更容易解析和理解
- 更多文档可在上下文窗口中查看。
实施指南
具体实现细节取决于你的编程语言和框架，但总体方法是相同的。
让我们通过一个 Express.js 的例子来了解一下。
1. 检测 Accept 标头
当请求到达时，检查标头是否Accept包含：text/markdowntext/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 请求，您应该看到：
- 响应头：
Content-Type: text/markdown; charset=utf-8 - 正文：不含 HTML 标签的原始 Markdown 内容
对于 HTML 请求，您应该会看到正常渲染的页面。
延伸阅读和资源
要了解更多实施方法，请查看以下资源：
- 接受标头文档
- @cramforce提供的Next.js 模板
- Laravel 设置指南，作者：@retlehs
- @skeptrune编写的静态网站、Cloudflare Workers 和 Caddy 设置指南。
（如果您已经创建了自己的指南、示例或模板，请在评论中分享，以便我将其添加到文章中。）
文章来源：https://dev.to/lingodotdev/how-to-serve-markdown-to-ai-agents-making-your-docs-more-ai-friend-4pdn