SEO 与 GEO

配置 SEO 元数据

以 Markdown 格式查看

当您想要自定义页面在搜索结果或社交预览中的显示方式时，您可以在站点级别设置默认值或在单个页面上覆盖它们。

Fern 会为您文档站点中的每个页面自动生成所有 SEO 元数据。搜索引擎和社交媒体预览无需任何配置即可开箱即用。

当您确实想要自定义 SEO 设置时，您可以在站点级别设置默认值或在单个页面上覆盖它们。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。

本页面上的元数据配置用于用户不可见的 SEO 和社交标签。对于可见的页脚链接，请参阅页脚链接配置。

工作原理

Fern 按以下顺序查找元数据值：

  1. 页面前置数据 — 特定页面的自定义 SEO 值
  2. 站点级 docs.yml — 所有页面的默认 SEO 值
  3. 自动默认值 — 从页面现有的 title、description、subtitle 或 excerpt 字段生成
示例

og:image 是在社交媒体预览中显示的图片。如果您没有在页面的前置数据中设置 og:image，Fern 会使用 docs.yml 中的站点级 og:image。如果两者都未配置，则完全省略该标签。

站点级默认值

在 docs.yml 中为整个站点设置默认 SEO 元数据。除非被页面特定元数据覆盖，否则这些设置适用于所有页面。

docs.yml
1metadata:
2  # 核心元数据
3  og:site_name: "Square Developer Documentation"
4  og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
5  og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services."
6  og:url: "https://developer.squareup.com/docs"
7  og:locale: "en_US"
8  canonical-host: "developer.squareup.com"
9
10  # 社交图片
11  og:image: "https://developer.squareup.com/images/docs-social-card.png"
12  og:image:width: 1200
13  og:image:height: 630
14  og:logo: "https://developer.squareup.com/images/square-logo.png"
15
16  # Twitter / X
17  twitter:title: "Square Developer Platform Documentation"
18  twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform."
19  twitter:handle: "@SquareDev"
20  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
21  twitter:site: "@Square"
22  twitter:card: "summary_large_image"

核心元数据

搜索引擎使用的身份和描述性字段，在社交平台之间共享。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。如果您的文档可以通过多个 URL 访问（例如，自定义域名和 buildwithfern.com 子域名），请设置 canonical-host 来告诉搜索引擎哪个 URL 是权威的。

metadata.og:site_name
string

用于 Open Graph 标签的网站名称。

metadata.og:title
string

在社交媒体预览中显示的标题。

metadata.og:description
string

在社交媒体预览中显示的描述。

metadata.og:url
string

文档的规范 URL。

metadata.og:locale
string

内容的语言环境（例如，en_US）。

metadata.canonical-host
string

文档网站的主机。用于设置元数据标签和站点地图等文档的规范 URL。默认为 instances 中定义的 URL。

社交图片

当您的文档在 LinkedIn、Slack、Discord 和其他平台上分享时显示的图片。使用 1200x630px 的图片以在各平台上获得最佳显示效果 — 这是标准的 Open Graph 尺寸，在大多数预览中都能正确渲染。避免在图片中嵌入文本，因为它在某些平台上可能会被裁剪。

metadata.og:image
string

在社交媒体预览中显示的图片。推荐尺寸为 1200x630 像素。

metadata.og:image:width
number

Open Graph 图片的宽度（像素）。

metadata.og:image:height
number

Open Graph 图片的高度（像素）。

string

公司 logo 的 URL。

动态 OG 图片 Beta

您可以启用动态 OG 图片生成，而不是为所有页面使用单一静态图片。启用后，Fern 会自动为没有在前置数据中设置图片的每个页面生成唯一的 og:image。

您可以选择为动态生成的 OG 图片提供自定义背景图片（og:background-image）。

docs.yml
1metadata:
2  og:dynamic: true
3  og:background-image: ./images/og-background.png # 可选
metadata.og:dynamic
boolean

当为 true 时，为没有设置自定义 og:image 的页面启用动态 OG 图片生成。

metadata.og:background-image
string

动态生成的 OG 图片的自定义背景图片。可以是 URL 或相对文件路径。相对路径从设置此属性的 YAML 文件位置解析（例如，docs.yml）。设置后，此图片将用作背景而不是纯色。

Twitter / X

控制您的文档在 X 上分享时如何在 Twitter Card 预览中显示。

metadata.twitter:title
string

在 Twitter Card 预览中显示的标题。

metadata.twitter:description
string

在 Twitter Card 预览中显示的描述。

metadata.twitter:handle
string

您公司的 Twitter 账号。

metadata.twitter:image
string

在 Twitter Card 预览中显示的图片。

metadata.twitter:site
string

您网站的 Twitter 账号。

metadata.twitter:card
string

Twitter Card 类型。选项有 summary、summary_large_image、app 或 player。

页面级覆盖

在页面的前置数据中配置 SEO 元数据，以控制单个页面在搜索结果和社交分享中的显示方式。这些设置会覆盖站点级默认值。

只有记录的 SEO 字段会作为元标签添加到 HTML <head> 中。自定义前置数据字段不会自动出现在页面元数据中。要添加自定义元数据，请使用自定义 JavaScript。

plantstore-quickstart.mdx
1---
2title: PlantStore API Quick Start
3headline: "Get Started with PlantStore API | Developer Documentation"
4keywords: plants, garden, nursery
5canonical-url: https://docs.plantstore.dev/welcome
6og:image: https://plantstore.dev/images/api-docs-banner.png
7og:image:width: 1200
8og:image:height: 630
9twitter:card: summary_large_image
10twitter:site: "@PlantStoreAPI"
11noindex: false
12nofollow: false
13---

基本元数据

搜索引擎使用的页面标题、URL 和关键字字段。当您需要为搜索引擎提供与显示的页面标题不同的标题时，请使用 headline。

headline
string

设置后，文档头部的 <title /> 标签将使用此值而不是 title 属性。例如，您的 title 可能是”快速入门”（显示在侧边栏和 H1 中），而 headline 可以是”快速入门 | PlantStore API 文档”来为搜索引擎提供更多上下文。如果未设置，Fern 使用 title 并附加您的站点名称。

canonical-url
string

覆盖此页面的规范 URL。必须是包含协议的完整 URL（例如，https://buildwithfern.com/learn/docs/content/frontmatter）。

keywords
string

与页面相关的逗号分隔关键字（例如，plants, garden, nursery）。只接受逗号分隔的字符串，不接受数组。

Open Graph

控制此页面在 LinkedIn、Slack、Discord 和其他支持 Open Graph 的平台上分享时的显示方式。为了优化显示效果，请将标题控制在 50-60 个字符之间，描述控制在 150-160 个字符之间。

og:site_name
string

您的网站在内容分享时应显示的名称。

og:title
string

您的页面在内容分享时应显示的标题。

og:description
string

您的页面在内容分享时应显示的描述。

og:url
string

您页面的 URL。

og:image
string

内容分享时显示的图片 URL。

og:image:width
number

图片的宽度（像素）。

og:image:height
number

图片的高度（像素）。

og:locale
string

页面的语言环境，通常格式为 language_TERRITORY（例如，en_US）。

string

内容分享时显示的 logo 图片 URL。

Twitter / X

控制此页面在 X 上分享时如何在 Twitter Card 预览中显示。

twitter:title
string

您的页面在推文中应显示的标题。

twitter:description
string

您的页面在推文中应显示的描述。

twitter:handle
string

页面创建者或站点的 Twitter 账号。

twitter:image
string

在推文中显示的图片 URL。

twitter:site
string

您网站的 Twitter 账号。

twitter:url
string

您页面的 URL。

twitter:card
string

在 Twitter 上分享时使用的卡片类型。选项：summary、summary_large_image、app、player。

索引设置

控制搜索引擎是否索引此页面或跟踪其链接。这些是不同的：noindex 完全从搜索结果中删除页面，而 nofollow 保持页面在结果中，但告诉搜索引擎不要通过其链接传递排名权重。

对于您希望在侧边栏中可见但从搜索结果中排除的页面使用 noindex — 例如，早期访问文档。要同时从侧边栏和搜索结果中隐藏页面，请在 docs.yml 中使用 hidden: true，这会自动处理两者 — 详见隐藏内容。谨慎使用 nofollow — 在文档中很少需要。

noindex
boolean

如果为 true，页面不会被搜索引擎索引，并且会从 llms.txt 端点中排除。

nofollow
boolean

如果为 true，搜索引擎不会跟踪页面上的任何链接。