Docsbook
概览

用于文档的 JSON-LD：重要的 schema 类型

JSON-LD 是嵌入 HTML 中的结构化数据，用于告诉搜索引擎和 AI 代理页面上的内容类型。对于文档而言，合适的 schema 类型可以让页面类型、步骤、面包屑和产品标识变得机器可读，而不是仅由页面布局隐含表达。

本文列出了值得添加的 schema 类型，指出了 Google 后来限制其富媒体搜索结果的那一种，并提供了可正常使用的示例。本文不承诺排名或引用：对于其中任何一种方法，都没有经过审查的技术能够对二者产生稳定且跨平台的因果影响。

摘要#

架构 适用页面 重要原因
TechArticle 操作指南和教程页面 告诉 Google“这是技术内容”
FAQPage 任何包含问答的页面 机器可读的问答对——但大多数网站不会显示富媒体搜索结果，详见下文
HowTo 分步指南 在 Google 中显示分步富媒体搜索结果
SoftwareApplication 产品概览页面 显示价格、评分和操作系统
Article 博客文章和公告 标准文章富媒体搜索结果
BreadcrumbList 每个文档页面 在搜索结果中显示面包屑导航
WebSite 网站根目录 SiteSearchAction 可启用 Google 搜索框

如果只做一项，请添加 TechArticle 和 BreadcrumbList。Docsbook 会自动添加这些内容。

为什么选择 JSON-LD 而不是 Microdata 或 RDFa#

JSON-LD 的优势在于：

  1. 它是一个独立的 <script> 块，与 HTML 标记解耦
  2. Google 明确更偏好它（在其文档中称为“推荐”）
  3. 更易于维护——无需改动布局即可更改架构
  4. AI 代理解析它的可靠性高于内联标记

Microdata 和 RDFa 仍然有效，但在 2026 年已属于旧式技术。

TechArticle：文档的默认类型#

对于大多数文档页面，TechArticle 是正确的架构：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to authenticate with OAuth",
  "description": "Step-by-step guide to authenticating users with OAuth 2.0",
  "author": {
    "@type": "Organization",
    "name": "Acme",
    "url": "https://acme.com"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-03-20",
  "publisher": {
    "@type": "Organization",
    "name": "Acme",
    "logo": {
      "@type": "ImageObject",
      "url": "https://acme.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://docs.acme.com/auth/oauth"
}
</script>

这将为你带来：

  • Google 会将该页面标记为权威技术内容
  • AI 代理往往会在引用中给予带有 TechArticle 标签的页面更高权重
  • dateModified 会告诉爬虫该页面是最新的

FAQPage：丰富摘要金矿#

如果您的页面具有问答结构，FAQPage 架构会让 Google 直接在搜索结果中显示这些问答。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I revoke an API key?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Open the dashboard, navigate to API Keys, find the key, click Revoke. Revocation is immediate."
    }
  }, {
    "@type": "Question",
    "name": "Can I have multiple API keys?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Yes. Replace this answer with the real limit from your own product."
    }
  }]
}
</script>

FAQPage 标记在 Google 中是否仍会产生富媒体搜索结果？#

对于几乎所有文档网站来说，不会。Google 在 2023 年限制了 FAQ 富媒体搜索结果，其文档现在也声明，该功能“仅对知名且权威的政府和医疗健康网站显示”（Google 搜索中心，FAQPage 结构化数据，读取于 2026-09-03）。任何承诺产品文档网站能通过 FAQ 摘要提升点击率的指南，描述的都是 2023 年以前的情况。

这并不是删除该标记的理由。FAQPage 仍然擅长做好一件事：以解析器无法误读的形式说明，这个区块是问题，而那个区块是答案。当页面确实是问题与答案的列表时，请保留它，并且不要期待 Google 中出现任何视觉变化。

HowTo：分步指南#

如果您有编号的分步指南，请使用 HowTo：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a custom domain for documentation",
  "step": [{
    "@type": "HowToStep",
    "text": "Open the dashboard and go to Settings → Domain"
  }, {
    "@type": "HowToStep",
    "text": "Enter your subdomain (docs.yourcompany.com)"
  }, {
    "@type": "HowToStep",
    "text": "Add a CNAME record in DNS pointing to cname.vercel-dns.com"
  }, {
    "@type": "HowToStep",
    "text": "Wait for SSL to provision (under 5 minutes)"
  }]
}
</script>

结果：Google 可能会显示每个步骤均已展开的分步富媒体搜索结果。

SoftwareApplication：产品页面#

您的产品概览页面应标记为 SoftwareApplication：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Acme",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "150",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "ratingCount": "247"
  }
}
</script>

这会在 Google 丰富搜索结果中显示价格和评分。请如实反映评分——Google 会惩罚虚高的 aggregateRating。

BreadcrumbList：每个页面#

每个页面都应在 JSON-LD 中包含面包屑导航。Google 会在搜索结果中显示它们，AI 代理会利用它们来理解层级结构：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Docs",
    "item": "https://docs.acme.com"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "Authentication",
    "item": "https://docs.acme.com/auth"
  }, {
    "@type": "ListItem",
    "position": 3,
    "name": "OAuth",
    "item": "https://docs.acme.com/auth/oauth"
  }]
}
</script>

在您的主页上声明站内搜索：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://docs.acme.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://docs.acme.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

这会在 Google 中您的搜索结果正下方直接启用搜索框。

同一页面上的多个架构#

您可以叠加架构。一个文档页面可能包含：

  • TechArticle 用于内容类型
  • BreadcrumbList 用于导航
  • FAQPage 如果有问答部分

这三者分别位于三个独立的 <script type="application/ld+json"> 块中。Google 会读取所有这些内容。

AI 代理如何处理 JSON-LD#

三种观察到的行为：

  1. 类型筛选 — 寻找教程的代理更偏好 TechArticle 和 HowTo，而不是 Article
  2. 提取捷径 — FAQPage 架构几乎会被逐字提取
  3. 信任信号 — 具有适当 Organization 和 publisher 的架构会获得更高权重

Docsbook 如何提供 JSON-LD#

Docsbook 会自动添加：

  • TechArticle 到每个文档页面
  • BreadcrumbList 到每个页面
  • FAQPage 到检测到问答模式的页面
  • 如果提供了元数据，则将 SoftwareApplication 添加到主页
  • 将带有 SearchAction 的 WebSite 添加到网站根目录

无需配置。该架构由现有的 Markdown 和 frontmatter 构建而成。

验证#

两个工具：

  • Google 富媒体搜索结果测试 — https://search.google.com/test/rich-results
  • Schema.org 验证器 — https://validator.schema.org/

在文档页面上运行这两项测试。修复所有警告。错误会阻止通过；警告不会。

Docsbook 会自动在每个页面上添加 JSON-LD。发布您的文档 →

Updated

此页面对您有帮助吗？

由...提供支持 Docsbook