SEO 优化

通过在 frontmatter 中设置标题、描述和元数据，优化文档在搜索引擎和社交预览中的呈现效果。

Jamdesk 自动完成的工作

优化内容

编写有效的 Frontmatter

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

页面标题

• 保持在 60 个字符以内，避免在搜索结果中被截断
• 将主要关键词放在标题开头附近
• 确保文档中的每个标题都不重复

描述

• 目标长度为 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 会将每个页面的路径附加到该地址，因此每个页面都会获得正确的页面级规范 URL：

{
  "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
---

---
title: API Reference
description: REST API endpoints and authentication
seo:
  "og:title": API Reference — Acme
  "og:image": /images/api-social-card.png
  "twitter:card": summary_large_image
  x-custom-tag: any custom meta value
---

支持的标签

Twitter / X 卡片类型

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

对于带品牌元素的 1200×630 卡片，请使用 summary_large_image，使图片以全宽显示。

全站默认图片

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

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

Sitemap 与 Robots.txt

每个 Jamdesk 站点都会在每次构建时自动生成 sitemap.xml 和 robots.txt。

查找位置

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

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

站点地图包含的内容

• 所有已发布页面（不包括 frontmatter 中带有 noindex 或 hidden 的页面）
• frontmatter 中提供的最后修改日期
• 每周变更频率

从站点地图中排除页面

在 frontmatter 中添加 noindex，即可将页面同时从站点地图和搜索引擎中排除：

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

带有 hidden: true 的页面也会自动排除。

JSON-LD 结构化数据

每个页面都会自动包含 schema.org 结构化数据，以 <script type="application/ld+json"> 标签提供两种 schema：

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

无需进行任何配置。搜索引擎会利用这些数据，在搜索列表中显示面包屑路径等丰富结果。

IndexNow

每次构建后，Jamdesk 会自动将发生更改的页面 URL 提交到 IndexNow，以加快搜索引擎索引速度。这样无需等待下一次抓取周期，即可通知 Bing、Yandex 及其他参与的搜索引擎你的内容已发生更改。

• 每次成功构建后触发
• 只提交实际发生更改的页面
• 非阻塞，不会延迟构建
• 无需配置

最佳实践

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

相关文章