我们的产品文档到底是在提升还是削弱AI可见性？文档应该如何结构化？

你的JavaScript问题很可能就是根源。以下是技术现实：

AI爬虫与Googlebot的区别：

你的React文档站点：

如果内容是在页面加载后通过JavaScript加载，AI爬虫看到的是：

<div id="root"></div>

而不是你的实际文档内容。

解决方案（从低到高的工作量）：

1. 预渲染/SSR —— 服务器端渲染页面，使HTML中包含内容
2. 静态网站生成 —— 将文档构建为静态HTML文件
3. 混合方式 —— 关键页面用SSR，交互部分用客户端渲染

快速验证：

1. 在你的文档页面使用“查看页面源代码”（不是检查元素）
2. 如果能看到实际内容 = 没问题
3. 如果看到的是空div = AI什么也看不到

可选框架：

• Docusaurus（静态+SSR）
• GitBook（预渲染）
• Mintlify（静态）
• VitePress（静态）

这些都能生成AI爬虫可读的HTML。

除了JS问题，结构优化也很重要：

AI喜欢的文档结构：

1. 清晰的标题层级

H1: 功能名称
  H2: 什么是[功能]？
  H2: 如何使用[功能]
    H3: 步骤1
    H3: 步骤2
  H2: 故障排查
  H2: FAQ

2. 先给答案的内容 每个部分都要先给出直接答案，再解释：

好的例子： “要安装Product X，请运行 npm install productx。此命令会从npm下载安装包并添加到你的依赖中。”

不好的例子： “当你准备开始使用我们的产品时，你需要确保一切已正确配置。首先，让我们聊聊依赖关系……”

3. 自包含的章节 每个H2部分都应能被独立提取后自洽。AI可能只引用某一个章节。

4. 明确的定义 不要假设上下文：

• “Product X是一款项目管理工具……”
• “API的速率限制为每分钟100次请求”
• “SSO（单点登录）允许用户……”

文档的schema标记——这一点常常被忽视：

文档必备schema：

1. Article/TechArticle schema

{
  "@type": "TechArticle",
  "headline": "如何配置SSO",
  "datePublished": "2026-01-01",
  "dateModified": "2026-01-05",
  "author": {
    "@type": "Organization",
    "name": "Your Company"
  }
}

2. FAQPage schema —— 用于故障排查/FAQ部分

{
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "如何重置我的密码？",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "进入设置 > 安全 > 重置密码……"
    }
  }]
}

3. HowTo schema —— 用于分步骤指南

{
  "@type": "HowTo",
  "name": "如何安装Product X",
  "step": [{
    "@type": "HowToStep",
    "text": "打开终端并运行npm install……"
  }]
}

对AI的影响：

Schema不能保证被AI引用，但它：

• 帮助AI理解内容类型
• 更易于信息提取
• 标识为结构化、可靠的信息
• 可提升Perplexity排名（约10%影响）

实施建议：

先在查询最多的话题上加FAQPage schema。最易实现且效果最大。

从文档SEO和AI角度总结：

我们对文档做了如下改动：

有效的URL结构：

好：/docs/features/sso-configuration 不好：/docs/article/12345

描述性URL让AI在阅读前就能理解内容。

内部链接：

大量交叉引用相关文档：

• “了解更多：[相关功能]”
• “参见：故障排查[主题]”
• “前提条件：[其他文档]”

有助于AI理解主题关系并建立权威性。

新鲜度信号：

• 明显展示“最后更新”日期
• 在sitemap中准确设置lastmod
• 实际更新内容（AI能检测到实质性变化）

这个讨论串太有帮助了。我的行动计划如下：

立即（第1周）：

1. 验证JS问题 —— 已完成，确认view-source显示空div
2. 研究预渲染 —— 正在看Prerender.io是否可快速修复
3. 优先处理高流量页面 —— 确定流量最高的50篇文档做SSR

短期（第2-4周）：

4. 实现预渲染 —— 让AI爬虫能看到HTML内容
5. 添加FAQPage schema —— 从故障排查部分入手
6. 重构重点文档 —— 答案优先，标题清晰

中期（第2-3月）：

7. 平台评估 —— 是否迁移到静态文档平台？
8. 全站schema实现 —— TechArticle、HowTo全站覆盖
9. 内容盘点 —— 保证各章节自包含

衡量成功的指标：

• view-source能看到实际内容
• 用 Am I Cited 跟踪AI引用
• 更多文档页面出现在AI答案中
• 具体文档URL出现在引用里

我的感悟：

我们的文档本可以成为最大的AI可见性资产——内容全面、准确且权威。但如果AI读不到，再好也没用。

给其他文档团队的建议：

现在就检查你的view-source。如果是空的，无论内容多好，在AI面前都是隐形的。

感谢大家！