

# 网页 .md 直出的工程实现：让 LLM 低成本消费你的文档

一个实际的问题：你的文档站/官网，LLM 读起来成本有多高？

拿一个典型的 HTML 页面算笔账：100KB 的页面里，正文可能只有 15KB，其余是导航、样式、脚本、推荐位、埋点。LLM 处理这个页面要先"去壳"（HTML→文本抽取），抽取质量还不稳定——表格经常被拍扁、代码块经常混入 UI 文字。

**.md 直出**就是解决这个问题的：每个页面提供一个同路径的纯 Markdown 版本，模型直接消费，零抽取损耗。这是海外 AI-native 文档站的标配做法（不少开源项目和大厂文档已全面跟进），国内落地的还很少。这篇讲完整的工程实现。

## 一、目标形态

```
https://example.com/pricing/          → HTML（给人看）
https://example.com/pricing/index.md  → Markdown（给模型读）
```

配套两件事：

1. HTML 页 head 里声明替代版本：

```html
<link rel="alternate" type="text/markdown" href="/pricing/index.md">
```

2. 站点根目录的 llms.txt（内容地图）里，所有链接直接指向 .md 版本

## 二、实现方案

### 方案 A：静态站点——构建时双输出

Hugo/Astro/Jekyll 等原生支持多格式输出，以 Hugo 为例：

```toml
# hugo.toml
[outputs]
  page = ["html", "markdown"]

[mediaTypes]
  [mediaTypes."text/markdown"]
    suffixes = ["md"]

[outputFormats]
  [outputFormats.markdown]
    mediaType = "text/markdown"
    baseName = "index"
```

Astro 用 content collections 的话，源文件本来就是 .md，加一个 passthrough 路由原样输出即可：

```js
// src/pages/[...slug].md.js
export function getStaticPaths() { /* 返回所有内容路径 */ }
export async function GET({ params }) {
  const entry = await getEntry(params.slug);
  return new Response(entry.body, {
    headers: { "Content-Type": "text/markdown; charset=utf-8" }
  });
}
```

### 方案 B：动态站点——预渲染 + 缓存

思路：构建流水线里对每个核心页跑一次 HTML→Markdown 转换，产物存对象存储/本地缓存，服务端按路径分发。

转换工具链选择：

```bash
# Node 系：turndown（可定制规则，保留表格需加 turndown-plugin-gfm）
# Python 系：markdownify / html2text
# 通用：pandoc（质量最稳，但重）
npx -y turndown-cli --gfm page.html -o page.md
```

nginx 分发配置：

```nginx
location ~ ^(.*)\.md$ {
    alias /var/www/md-cache$1.md;
    default_type text/markdown;
    add_header Content-Type "text/markdown; charset=utf-8";
    # 缓存策略：和 HTML 版本同周期失效
    expires 1h;
}
```

关键纪律：**Markdown 版本必须和 HTML 版本同源生成**——从同一份内容数据（CMS 字段/MDX 源文件）分别渲染两种格式。如果是"HTML 上线后再反向抽取成 MD"，两个版本会漂移，给 AI 的和给人看的不一致，交叉验证时反受其害。

### 方案 C：全站聚合版 llms-full.txt

对核心事实页（FAQ/定价/关于/产品说明），额外生成一份全文聚合文件：

```bash
# 构建脚本里追加一步：把核心页的 md 拼接
cat content/about.md content/faq.md content/pricing.md \
  > public/llms-full.txt
```

价值：深度抓取型消费方（Agent、研究型检索）一次请求拿到全部核心事实，不用逐页爬。控制在 200KB 以内（约 5 万 token），超了就按板块拆分。

## 三、质量校验：转换不是无损的

HTML→Markdown 的自动转换有固定的坑，上线前跑一遍校验：

```python
#!/usr/bin/env python3
"""md 直出质量校验：表格/代码块/标题层级完整性检查"""
import sys, re

def check(md_text, name):
    issues = []
    # 表格：HTML 转换常把表格拍扁成一行文字
    if "<table" in md_text or re.search(r"\|.*\|.*\|", md_text) is None:
        if "table" in md_text.lower():
            issues.append("疑似表格丢失或拍扁")
    # 代码块：围栏完整性
    if md_text.count("```") % 2 != 0:
        issues.append("代码块围栏不配对")
    # 标题层级：H1 唯一性
    h1 = len(re.findall(r"^# ", md_text, re.M))
    if h1 != 1:
        issues.append(f"H1 数量异常: {h1}")
    # 残留 HTML 标签
    leftover = re.findall(r"<(div|span|nav|footer)[^>]*>", md_text)
    if leftover:
        issues.append(f"残留 HTML 标签: {set(leftover)}")
    print(f"{'✅' if not issues else '❌'} {name}: {'; '.join(issues) or 'OK'}")

for path in sys.argv[1:]:
    check(open(path, encoding="utf-8").read(), path)
```

人工再抽查两类页面：带复杂表格的（定价页）、带代码块的（文档页）——这两类是转换质量的重灾区。

## 四、验证消费效果

```bash
# 1. 模拟 AI 爬虫请求，确认返回类型正确
curl -sI -A "GPTBot" https://example.com/pricing/index.md | grep -i content-type
# 期望: text/markdown

# 2. 实测消费质量：把 .md URL 丢给支持联网的 AI
#    问"总结这个页面"，对比总结与原文的一致性

# 3. 日志观察：.md 路径的 AI 爬虫访问量
grep "\.md" /var/log/nginx/access.log | grep -cE "GPTBot|ClaudeBot|Bytespider"
```

第 3 项做成周报趋势：llms.txt 里 .md 链接的访问量应该在部署后 2-4 周爬升——没动静就回头查 robots 放行和 llms.txt 发现机制。

## 总结

.md 直出的本质是把"内容消费"从渲染态回退到源数据态——人消费渲染态（HTML），模型消费源数据态（Markdown）。工程量不大：静态站一天，动态站两三天，核心纪律只有一条：**两种格式同源生成，永不漂移。**

做完这一步，加上 robots 放行和 llms.txt 导览，你的站点对 AI 的可读性就齐了：进得来、找得到、读得懂。

---

*本文基于Winin(winin.ai)。各家 AI 爬虫对 .md 版本的实际消费行为不透明且持续演进，建议部署后用访问日志和实测验证。欢迎评论区交流你的实现方案。*



拿一个典型的 HTML 页面算笔账：100KB 的页面里，正文可能只有 15KB，其余是导航、样式、脚本、推荐位、埋点。LLM 处理这个页面要先"去壳"（HTML→文本抽取），抽取质量还不稳定——表格经常被拍扁、代码块经常混入 UI 文字。

GEO怎么做：网页 .md 直出的工程实现：让 LLM 低成本消费你的文档

人工智能

.md直出工程实现：静态站用Hugo/Astro构建双输出，动态站用turndown预渲染+缓存。核心纪律是HTML与Markdown同源生成防漂移，配套llms.txt导览和llms-full.txt聚合，用质量校验脚本查表格/代码块残留。部署后观察AI爬虫访问日志验证消费效果。

对象存储

代码解释

路由

Python

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

GEO怎么做：网页 .md 直出的工程实现：让 LLM 低成本消费你的文档-腾讯云开发者社区-腾讯云

GEO怎么做：网页 .md 直出的工程实现：让 LLM 低成本消费你的文档

GEO怎么做：网页 .md 直出的工程实现：让 LLM 低成本消费你的文档

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐