SEO 优化

在 frontmatter 中设置标题、描述和元数据，以控制你的文档在搜索引擎和社交预览中的显示方式。

Jamdesk 自动完成的工作

优化内容

编写有效的 Frontmatter

---
title: User Authentication    # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication  # 120-160 characters
---

页面标题

• 保持在 60 个字符以内，计入你的标题格式所添加的站点名称。过长的标题会在搜索结果中被截断
• 将主要关键词放在靠近开头的位置
• 确保每个标题在你的文档中都是唯一的

默认情况下，浏览器标签页和搜索结果中的标题为 页面标题 — 站点名称。你可以在 docs.json 中使用 seo.titleTemplate 进行修改。将 %s 放在页面标题的位置：

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

这样，标题为 Getting started 的页面将显示为 Getting started | Acme。如果只想使用页面标题、不包含站点名称，可以单独使用 "%s"。缺少 %s 的模板会导致构建失败，jamdesk validate 会显示该错误。链接预览（og:title 和 twitter:title）仍然只显示页面标题。

部分页面不会使用模板。没有 title 的页面会显示你的 name 加上 "Documentation"，例如 Acme Documentation；如果你的 name 已经以 "Docs" 或 "Documentation" 结尾，则只显示 name。标题与你的 name 相同的页面只显示该标题。

jamdesk validate 和 jamdesk dev 从 CLI 1.1.220 版本开始支持 seo.titleTemplate。使用 npm i -g jamdesk@latest 升级。

描述

• 目标长度为 120-160 个字符
• 概括读者将学到的内容
• 自然地包含相关关键词

控制索引收录

全站设置

在 docs.json 中设置默认的 robots 行为：

{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}

单页控制

在 frontmatter 中覆盖特定页面的索引设置：

---
title: Internal Notes
noindex: true
---

以下情况请使用 noindex：

• 草稿或正在编写中的页面
• 内部文档
• 已弃用但需保留以供参考的内容

搜索索引与 AI 摄取

robots 元数据和 noindex 控制的是搜索引擎：页面是否出现在 Google 和你的 sitemap.xml 中。它们对 AI 工具读取的 llms.txt 和 llms-full.txt 文件没有影响。将 seo.ai.llmsTxt 设置为 false 可停止发布这些文件（参见关闭 llms.txt）。这两项控制是相互独立的：页面可以被搜索引擎索引，同时排除在 AI 采集之外，反之亦然。

规范 URL

如果你的文档可以通过多个 URL 访问，请设置规范 URL：

---
title: Getting Started
canonical: https://docs.example.com/getting-started
---

你也可以在 docs.json 中设置全站的规范 URL 基础地址。Jamdesk 会将每个页面的路径追加到该地址之后：

{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}

社交预览与 Open Graph

Jamdesk 为每个页面生成一张带品牌标识的 1200×630 社交卡片。你可以在 frontmatter 中使用扁平的顶层键或嵌套的 seo: 块来覆盖任何社交标签。当同一个键两种方式都设置时，扁平的顶层值优先。

---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---

支持的标签

Twitter / X 卡片类型

twitter:card 标签控制分享链接时 X（以及其他平台）所使用的布局：

使用 summary_large_image 可获得带品牌标识的 1200×630 卡片，图片以全宽显示。

全站默认图片

在 docs.json 中为每个页面设置备用社交图片。任何自行设置了 og:image 的页面都会覆盖该默认值：

{
  "seo": {
    "metatags": {
      "og:image": "https://docs.acme.com/images/default-card.png"
    }
  }
}

自定义社交卡片

除非你在 docs.json 中添加 seo.socialCard，否则生成的卡片将保持当前外观。只需设置你想更改的键：

{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}

卡片只能绘制 SVG、PNG 和 JPG 格式的徽标。Jamdesk 会在构建时将仓库中的 PNG 和 JPG 徽标文件转换为 WebP。这样，卡片通常会显示你的 favicon，并保留站点名称，即使设置了 siteName: false。若要在卡片上显示完整徽标，请使用 SVG 徽标。深色卡片请使用 SVG 格式的 logo.dark。

卡片无法绘制 SVG 徽标中的文字，这些文字会显示为空白。请在设计工具中将文字转换为轮廓（路径），然后重新导出 SVG。在 Figma 中，选中文字并使用 Flatten。在 Illustrator 中，使用 Type > Create Outlines。当构建过程在卡片的 SVG 徽标中发现文字时，会显示相应提示。设置为完整 URL（https://...）的徽标不会被检查。

当徽标颜色与卡片背景对比不明显时，徽标文字会回退为普通文字颜色。除非该颜色与卡片背景几乎相同，否则色条会保留你的品牌色；若几乎相同，则色条显示为灰色。

默认情况下，Jamdesk 会在你的 og:image 上方绘制页面标题。设置 "customImage": "replace" 可以原样显示自带文字或设计的图片。

请选择与用作卡片背景的 og:image 相匹配的 theme：深色图片使用 dark，浅色图片使用 light。

在 replace 模式下，Jamdesk 不会在图片上绘制标题。seo.metatags 中的 og:image 适用于每个页面。自行设置了 og:image 的页面则使用该图片。只有两者都未设置的页面才会生成卡片。请使用 1200×630 的 PNG 或 JPG。部分平台不显示 WebP 或 SVG 图片。

社交网站会缓存链接预览。已分享过的链接在你更改这些设置后，可能仍会在一段时间内显示旧卡片。请使用 OpenGraph 预览工具检查新卡片。

站点地图与 Robots.txt

Jamdesk 每次构建时都会生成 sitemap.xml 和 robots.txt。

查找位置

URL 取决于你的文档位于根域名还是 /docs 子路径下：

https://docs.acme.com/sitemap.xml
https://docs.acme.com/robots.txt

站点地图包含的内容

• 所有已发布的页面（不包括带有 noindex 或 hidden frontmatter 的页面）
• 可用时，取自 frontmatter 的最后修改日期
• 每周更新频率

从站点地图中排除页面

在 frontmatter 中添加 noindex，即可使页面不出现在站点地图和搜索引擎中：

---
title: Internal Notes
noindex: true
---

设置了 hidden: true 的页面同样会被排除。

JSON-LD 结构化数据

每个页面都会包含 schema.org 结构化数据，以 <script type="application/ld+json"> 标签的形式输出，包含两种模式：

• WebSite：你的站点名称、URL 和描述（来自 docs.json）。
• BreadcrumbList：从首页到当前页面的导航路径，根据你的 navigation 配置生成。

无需任何配置。搜索引擎会使用这些数据生成富媒体结果，例如搜索列表中的面包屑导航。

IndexNow

Jamdesk 在每次构建后，会将变更页面的 URL 提交给 IndexNow。Bing、Yandex 以及其他参与的搜索引擎无需等待下一次抓取周期，即可得知这些变更。

• 每次构建成功后触发
• 仅提交已变更的页面
• 非阻塞。绝不会延迟你的构建
• 无需任何配置

最佳实践

发布前请逐项检查以下清单：

相关文章