Docsbook 如何构建页面头部

本页面介绍其机制：Docsbook 为它托管的每个页面放入 <head> 和 sitemap.xml 中的内容，并按照代码解析的顺序进行说明，这样你无需使用 curl 请求，就能预测输出结果。至于这对你有什么用，以及需要开启哪些功能，请从 SEO 索引开始。

页面上的标题是什么，它来自哪里？#

Docsbook 页面中的 <title> 按三个步骤确定，按首次匹配为准：

顺序	来源	为何优先
1	前置元数据 `title:`	三者中唯一一个可以编辑而不改变读者在页面上看到的内容的来源。
2	正文 `# H1`	真正的标题，已经为人类读者编写。
3	从文件名派生的标题	永远不会为空；页面始终有一行 SERP 文本。

然后会附加工作区名称，恰好一次，形式为 Page title — Workspace，如果标题已经将其作为独立单词写出，则跳过。 "Docsbook" 中的 "Docs" 不算 —— 匹配项两侧的字符都必须是非单词字符；判断依据是 Unicode 字母和数字，而不是 ASCII 字符，因此西里尔字母或 CJK 工作区名称与拉丁字母名称的匹配方式相同。标题仅为工作区名称的页面（即站点根页面）会变成 Workspace — Documentation。最终字符串会作为绝对标题输出，从而阻止全站的 %s | Docsbook 模板再次附加品牌文本。

在翻译页面上，标题来自缓存的翻译元数据；否则来自已存储翻译 HTML 中的第一个 <h1> —— 因此，中文页面会使用中文标题。描述则会有意保留为源语言： Docsbook 不会为其自动生成翻译。

什么是元描述，其中哪些内容会被剔除？#

顺序：先处理前置元数据 description:，然后处理页面自身开头的段落。

正文文本在成为描述之前会经过清理：HTML 注释（小组件标记就是这种注释）、{icon-name} 标记、标题、图片、围栏代码和行内代码、强调字符、原始 HTML 标签、列表项目符号以及引用块标记都会被移除；Markdown 链接会折叠为其链接文本，而不会将其 URL 带入句子。字符数不超过 20 的段落会作为片段被丢弃。

两种长度在一次处理中从同一来源生成：160 个字符用于 <meta name="description">，400 个字符用于 og:description 和 JSON-LD description。手动编写的前置元数据描述会同时填充两者。截断会落在单词边界处；如果句子末尾位于长度预算的后半部分，则优先在句末截断；否则文本会以省略号结尾。

页面将哪个 URL 称为规范 URL？#

每个页面有一个规范 URL，按以下顺序确定：

您的自定义域名（当工作区拥有自定义域名时）。此时，*.docsbook.io 镜像提供 Disallow: /，而不是作为第二个副本存在。
产品所有的顶级域路径，用于 Docsbook 自身的文档。
顶级域短路径，用于展示工作区，因为该 URL 响应 200 —— 子域名形式会重定向到该 URL。
https://<owner>.docsbook.io/<repo>/<path>，用于其他所有情况。

翻译页面也遵循相同的四个分支，并将区域设置插入路由器实际提供页面的位置。en 会特殊处理并回退到无前缀 URL，因为 /en/page 和 /page 提供字节完全相同的内容；而对于实际未翻译页面的区域 URL，页面会呈现源文本，因此其规范 URL 会指向源 URL，而不是声称自身具有权威性。

哪些语言会作为备用语言进行宣传？#

hreflang 集合包含源 URL 中的 x-default 和 en，此外还包含每种已启用语言各一个条目，前提是该页面确实已翻译成该语言。启用某种语言并不会将其添加进来：未翻译的区域设置 URL 会将规范 URL 指向其他位置，而其中任意一个成员出现这种情况，就足以使整个集合失效。带有 noindex 的页面根本不会获得任何集合，而不是留下一个悬空集合。

站点地图会特意不输出页面级备用语言。这是因为它无法承担逐页翻译检查的开销，因此它构建的任何集合都会列出每个已启用的区域设置，并重新引入页面级集合正是为了避免的矛盾。

每个页面都会输出 OpenGraph（og:title、在 400 个字符长度限制下的 og:description、og:url = 规范 URL、og:site_name、og:type: article、og:locale）以及一张类型为 summary_large_image、包含 160 个字符描述的 X 卡片。图像按页面生成，尺寸为 1200×630，缓存 24 小时，并以工作区的配色呈现工作区标识、作为眉题的分区名称、页面标题（截取前 64 个字符，超过 30 个字符时缩小字体）以及截取前 130 个字符的描述。在自定义域名下，该卡片使用相同的图像，通过根域名的绝对 URL 请求，但其中的 og:description 携带的是 160 个字符的字符串，而不是 400 个字符的字符串。

页面携带哪些 robots 指令？#

四条规则，按严格优先级排列：

条件	输出
管理员预览（`?preview=true`）	`noindex, follow`
全站 SEO 开关关闭	`noindex, nofollow`
页面 frontmatter `noindex`	`noindex, follow`
其他情况	`index, follow`

noindex: true、noindex: yes、noindex: 1 以及 robots: noindex 拼写形式都算作有效。其他任何情况——缺失、false、index——均表示允许索引。

robots.txt 因主机而异。根域名提供包含 Crawl-delay: 10 的宽松通配规则，禁止访问应用自身的非内容路径，在 Crawl-delay: 5 中明确列出十八个 AI 和搜索爬虫，直接阻止十三个高流量、低引用价值的爬虫，并为每个可发现的网站列出一行 Sitemap:。工作区子域名提供相同的机器人策略，并附带自己的一行 Sitemap:。自定义域名提供机器人策略，但没有 Sitemap: 行——它目前还没有自己的站点地图，而将爬虫指向镜像站点的站点地图会为每个页面宣传第二个主机。Crawl-delay 是一种礼貌性设置，而非标准：RFC 9309 仅定义了 user-agent、allow 和 disallow，而 Google 只额外支持 sitemap，没有其他内容——“不支持其他字段，例如 crawl-delay”。

sitemap.xml 中包含哪些内容？#

每位所有者对应一个站点地图，最多每小时重建一次。对于每个已编入索引的仓库，它会列出每个 Markdown 文件，将仓库根目录中的 README 映射到站点根目录，并将其他每个文件映射到其自身路径。每个条目包含：

lastmod — 修改该文件的最后一次提交日期，取自源仓库。只有在无法读取提交历史时，才会使用渲染时间。
changefreq — weekly。
priority — 对于着陆页为 0.9，对于内部页面为 0.7，对于它们的翻译则为 0.8 / 0.6。

只有在翻译确实存在时，才会列出翻译后的 URL，并且在生成文件前会合并重复的 URL。无法读取其目录树的仓库会被静默丢弃，其余站点地图仍会正常提供：返回 500 错误的站点地图，其代价高于少列出一个站点。

带有 noindex 的页面仍然会被列出。识别该标志意味着读取每个页面的内容，而构建站点地图时特意不会这样做；页面自身的指令会在访问时得到遵守，因此代价只是一次爬取访问。

会生成哪些结构化数据？#

在 Docsbook 托管的主机上，每个页面都会生成一个包含三个节点的 JSON-LD @graph：

Organization — 工作区、其 URL、其 GitHub 个人资料，以及在设置后显示的徽标。
TechArticle — 标题、描述、规范 URL、inLanguage、 datePublished 和 dateModified（来自源代码仓库的提交历史）、作者、发布者、mainEntityOfPage。
BreadcrumbList — 所有者 → 站点 → 每个路径段，使用与 <link rel="canonical"> 相同的规范构建器生成，因此不会出现名称与规范标签不一致的主机的面包屑。

启用 AEO 后，会添加 speakable；只有当页面确实包含相应结构时，才会出现 FAQPage / HowTo 节点。启用 GEO 后，会从 frontmatter 或最近一次提交的作者中添加一个 Person 作者。

锚点、渲染模式和主机#

锚点。 标题 ID 由渲染器自身的 slug 生成器生成，Docsbook 发出的每个深层链接——搜索结果、AI 引用——都是通过调用同一个库计算得出的，而不是重新推导该字符串。重复标题解析为首次出现的标题。

渲染模式。 对公共页面的匿名请求通过缓存的服务器渲染路由提供服务（24 小时窗口）；已登录和预览请求则转为动态渲染，并且绝不会由 CDN 缓存。无论哪种情况，爬虫都会收到完整的 HTML——机器人与您的文本之间不会隔着客户端渲染步骤。

自定义域名与共享域名。 在自定义域名上，规范 URL、标题、描述、卡片和一个 TechArticle 节点都会存在，并且会执行机器人策略。以下五项除外：全站 SEO 开关和每页的 noindex（页面会无条件地以 index, follow 提供服务）、hreflang 集合、BreadcrumbList 和 Organization 节点、页面迁移重定向，以及 GEO 信号——没有 TL;DR 区块、没有可见的“已更新”行，并且 TechArticle 作者始终是一个以仓库所有者命名的 Person。请参阅限制。

为什么制定这些规则（依据）#

规则	为什么它对消费者有效	来源
每个页面一个 `<title>`，品牌名称追加一次	Google 将 `<title>` 列为标题链接来源中的首要来源，并警告不要在 `<title>` 元素中使用“重复或模板化文本”	标题链接
为每个页面提供描述，绝不使用全站统一的字符串	“网站每个页面上相同或相似的描述没有帮助”	摘要
规范链接指向返回 200 的 URL，绝不指向重定向	`rel="canonical"` 是“强信号”，Google 建议在规范页面上使用指向自身的规范链接	整合重复网址
`hreflang` 中仅包含确实已翻译的语言区域版本	“如果页面 X 链接到页面 Y，页面 Y 必须链接回页面 X……否则这些注释可能会被忽略”	本地化版本
使用真实的提交日期作为 `lastmod`	Google 使用 `<lastmod>`，“前提是它始终准确且可验证……”	创建站点地图
结构化数据仅用于页面实际包含的内容	“不要添加有关用户不可见信息的结构化数据”	结构化数据简介
使用服务器渲染的 HTML，而不是客户端渲染	Google 会在队列中渲染 JavaScript，页面“可能会停留几秒钟，但也可能需要更长时间”，并且“并非所有机器人都能运行 JavaScript”	JavaScript SEO 基础知识
1200×630 卡片图片	“使用至少为 1200 x 630 像素的图片”，接近 1.91:1 的比例	分享图片

限制与未决问题#

priority 和 changefreq 是装饰性的。 Docsbook 会生成它们，而 Google 明确表示：“Google 会忽略 <priority> 和 <changefreq> 值。”sitemaps.org 协议补充说明，优先级“很可能不会影响您的 URL 的排名”。它们不会给 Google 带来任何成本或收益；其他搜索引擎则各不相同。
TechArticle 不在 Google 的 Article 富媒体结果列表中。 它是一个真实的 schema.org 类型（Thing > CreativeWork > Article > TechArticle），能够准确描述内容，但 Google 的 Article 文档表示，对象“必须基于以下某一种 schema.org 类型：Article、NewsArticle、BlogPosting”。应将该节点视为准确的描述，而不是富媒体结果资格。结构化数据也没有被记录为排名因素：Google 的介绍将其描述为使页面 有资格获得增强展示，并未提及排名。
尚待确认的问题：400 字符的 og:description 能带来什么。 Docsbook 会生成它，因为该标签有空间，而 <meta description> 没有。我们查阅的资料中没有任何来源记录特定消费者如何截断 og:description，而 OpenGraph 协议也没有规定长度。应将 400 视为内部选择，而不是经过测量的最优值。
自定义域名页面会忽略您的索引开关。 全站 SEO 开关和每页的 noindex 仅在 Docsbook 托管的主机上生效；在自定义域名上，无论如何页面都会以 index, follow 提供。/sitemap.xml 在那里也无法解析，因此其 robots.txt 不包含任何 Sitemap: 行，而且通过 Docsbook 重命名的页面仅在共享域名上保留其重定向。如今若要让自定义域名上的页面不被编入索引，请不要将其发布到仓库中。
根据 sitemaps.org 协议和 Google 自身的限制，单个站点地图上限为 50,000 个 URL / 50 MB。 Docsbook 为每个所有者生成一个站点地图，且不会拆分；目前尚未处理超过该上限的所有者。

Updated Sep 5, 2026