> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI0NDBhYzFhNS1jMDAxLTQ0MTItOGU5Yi01MmRjNDY0MTc2MGYiLCJleHAiOjE3NzgyOTQzNjcsImlhdCI6MTc3ODI5NDA2N30.pUZQoNy4lvBsZgsqu4n1D8ScZIRRSfjmtwNLfn0JkYU
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.
# 配置 SEO 元数据
> 通过页面级前置数据和站点级设置在 Fern 文档中配置 SEO 元数据。控制标题、描述、社交媒体预览和站点地图时间戳。
当您想要自定义页面在搜索结果或社交预览中的显示方式时，您可以在[站点级别](#site-wide-defaults)设置默认值或在[单个页面](#page-level-overrides)上覆盖它们。
Fern 会为您文档站点中的每个页面自动生成所有 SEO 元数据。搜索引擎和社交媒体预览无需任何配置即可开箱即用。
当您确实想要自定义 SEO 设置时，您可以在[站点级别](#website-metadata)设置默认值或在[单个页面](#page-level-configuration)上覆盖它们。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。
本页面上的元数据配置用于用户不可见的 SEO 和社交标签。对于可见的页脚链接，请参阅[页脚链接配置](/learn/docs/configuration/site-level-settings#footer-links-configuration)。
## 工作原理
Fern 按以下顺序查找元数据值：
1. **页面前置数据** — 特定页面的自定义 SEO 值
2. **站点级 `docs.yml`** — 所有页面的默认 SEO 值
3. **自动默认值** — 从页面现有的 `title`、`description`、`subtitle` 或 `excerpt` 字段生成
`og:image` 是在社交媒体预览中显示的图片。如果您没有在页面的前置数据中设置 `og:image`，Fern 会使用 `docs.yml` 中的站点级 `og:image`。如果两者都未配置，则完全省略该标签。
## 站点级默认值
在 `docs.yml` 中为整个站点设置默认 SEO 元数据。除非被页面特定元数据覆盖，否则这些设置适用于所有页面。
```yaml docs.yml
metadata:
# 核心元数据
og:site_name: "Square Developer Documentation"
og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services."
og:url: "https://developer.squareup.com/docs"
og:locale: "en_US"
canonical-host: "developer.squareup.com"
# 社交图片
og:image: "https://developer.squareup.com/images/docs-social-card.png"
og:image:width: 1200
og:image:height: 630
og:logo: "https://developer.squareup.com/images/square-logo.png"
# Twitter / X
twitter:title: "Square Developer Platform Documentation"
twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform."
twitter:handle: "@SquareDev"
twitter:image: "https://developer.squareup.com/images/twitter-card.png"
twitter:site: "@Square"
twitter:card: "summary_large_image"
```
### 核心元数据
搜索引擎使用的身份和描述性字段，在社交平台之间共享。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。如果您的文档可以通过多个 URL 访问（例如，自定义域名和 `buildwithfern.com` 子域名），请设置 `canonical-host` 来告诉搜索引擎哪个 URL 是权威的。
用于 Open Graph 标签的网站名称。
在社交媒体预览中显示的标题。
在社交媒体预览中显示的描述。
文档的规范 URL。
内容的语言环境（例如，`en_US`）。
文档网站的主机。用于设置元数据标签和站点地图等文档的规范 URL。默认为 `instances` 中定义的 URL。
### 社交图片
当您的文档在 LinkedIn、Slack、Discord 和其他平台上分享时显示的图片。使用 1200x630px 的图片以在各平台上获得最佳显示效果 — 这是标准的 Open Graph 尺寸，在大多数预览中都能正确渲染。避免在图片中嵌入文本，因为它在某些平台上可能会被裁剪。
在社交媒体预览中显示的图片。推荐尺寸为 1200x630 像素。
Open Graph 图片的宽度（像素）。
Open Graph 图片的高度（像素）。
公司 logo 的 URL。
### 动态 OG 图片 \[#dynamic-og-images]
您可以启用动态 OG 图片生成，而不是为所有页面使用单一静态图片。启用后，Fern 会自动为没有在[前置数据中设置](#open-graph)图片的每个页面生成唯一的 `og:image`。
您可以选择为动态生成的 OG 图片提供自定义背景图片（`og:background-image`）。
```yaml docs.yml
metadata:
og:dynamic: true
og:background-image: ./images/og-background.png # 可选
```
当为 `true` 时，为没有设置自定义 `og:image` 的页面启用动态 OG 图片生成。
动态生成的 OG 图片的自定义背景图片。可以是 URL 或相对文件路径。相对路径从设置此属性的 YAML 文件位置解析（例如，`docs.yml`）。设置后，此图片将用作背景而不是纯色。
### Twitter / X
控制您的文档在 X 上分享时如何在 Twitter Card 预览中显示。
在 Twitter Card 预览中显示的标题。
在 Twitter Card 预览中显示的描述。
您公司的 Twitter 账号。
在 Twitter Card 预览中显示的图片。
您网站的 Twitter 账号。
Twitter Card 类型。选项有 `summary`、`summary_large_image`、`app` 或 `player`。
## 页面级覆盖
在页面的前置数据中配置 SEO 元数据，以控制单个页面在搜索结果和社交分享中的显示方式。这些设置会覆盖站点级默认值。
只有记录的 SEO 字段会作为元标签添加到 HTML `` 中。自定义前置数据字段不会自动出现在页面元数据中。要添加自定义元数据，请使用[自定义 JavaScript](/learn/docs/customization/custom-css-js#custom-javascript)。
```mdx
---
title: PlantStore API Quick Start
headline: "Get Started with PlantStore API | Developer Documentation"
keywords: plants, garden, nursery
canonical-url: https://docs.plantstore.dev/welcome
og:image: https://plantstore.dev/images/api-docs-banner.png
og:image:width: 1200
og:image:height: 630
twitter:card: summary_large_image
twitter:site: "@PlantStoreAPI"
noindex: false
nofollow: false
---
```
### 基本元数据
搜索引擎使用的页面标题、URL 和关键字字段。当您需要为搜索引擎提供与显示的页面标题不同的标题时，请使用 `headline`。
设置后，文档头部的 `` 标签将使用此值而不是 `title` 属性。例如，您的 `title` 可能是"快速入门"（显示在侧边栏和 H1 中），而 `headline` 可以是"快速入门 | PlantStore API 文档"来为搜索引擎提供更多上下文。如果未设置，Fern 使用 `title` 并附加您的站点名称。
覆盖此页面的规范 URL。必须是包含协议的完整 URL（例如，`https://buildwithfern.com/learn/docs/content/frontmatter`）。
与页面相关的逗号分隔关键字（例如，`plants, garden, nursery`）。只接受逗号分隔的字符串，不接受数组。
### Open Graph
控制此页面在 LinkedIn、Slack、Discord 和其他支持 Open Graph 的平台上分享时的显示方式。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。
您的网站在内容分享时应显示的名称。
您的页面在内容分享时应显示的标题。
您的页面在内容分享时应显示的描述。
您页面的 URL。
内容分享时显示的图片 URL。
图片的宽度（像素）。
图片的高度（像素）。
页面的语言环境，通常格式为 `language_TERRITORY`（例如，`en_US`）。
内容分享时显示的 logo 图片 URL。
### Twitter / X
控制此页面在 X 上分享时如何在 Twitter Card 预览中显示。
您的页面在推文中应显示的标题。
您的页面在推文中应显示的描述。
页面创建者或站点的 Twitter 账号。
在推文中显示的图片 URL。
您网站的 Twitter 账号。
您页面的 URL。
在 Twitter 上分享时使用的卡片类型。选项：`summary`、`summary_large_image`、`app`、`player`。
### 索引设置
控制搜索引擎是否索引此页面或跟踪其链接。这些是不同的：`noindex` 完全从搜索结果中删除页面，而 `nofollow` 保持页面在结果中，但告诉搜索引擎不要通过其链接传递排名权重。
对于您希望在侧边栏中可见但从搜索结果中排除的页面使用 `noindex` — 例如，早期访问文档。要同时从侧边栏和搜索结果中隐藏页面，请在 `docs.yml` 中使用 `hidden: true`，这会自动处理两者 — 详见[隐藏内容](/learn/docs/customization/hiding-content)。谨慎使用 `nofollow` — 在文档中很少需要。
如果为 `true`，页面不会被搜索引擎索引，并且会从 [`llms.txt`](/learn/docs/ai-features/llms-txt) 端点中排除。
如果为 `true`，搜索引擎不会跟踪页面上的任何链接。