> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIwMmZkMjY0NS1mZTI3LTRjZjYtODUyYy00NjNhMTM4YmRmMGEiLCJleHAiOjE3NzgyNTg5MzEsImlhdCI6MTc3ODI1ODYzMX0.ydtco8wbWNzpKdy0z2nZlDAUPq-W8vBT4TCVIPFsavQ
>
> 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.

# 页面级设置

> 使用前置事项设置各种页面属性和元数据。

您可以选择使用前置事项来设置每个页面的标题、完整路径覆盖、元描述、建议编辑页面的 URL 以及 OpenGraph 图片。您还可以使用前置事项来禁用某些页面元素，如目录、页面反馈和页面操作。

<Tip>
  对于超出前置事项选项的高级样式和功能自定义，请参见 [自定义 CSS 和 JavaScript](/docs/customization/custom-css-js)。
</Tip>

## 前置事项语法

前置事项必须添加到 `.md` 或 `.mdx` 文件的顶部，在其余内容之前。使用三个破折号来指示前置事项的开始和结束，如下所示：

<CodeBlock title="前置事项示例">
  ```mdx
  ---
  title: 使用前置事项自定义内容
  subtitle: 设置标题、添加元描述等
  slug: frontmatter
  description: 使用前置事项设置页面标题、副标题、路径、元描述、OpenGraph 图片和建议编辑的 URL。
  keywords: frontmatter, seo, customization, metadata
  og:site_name: Your Company Inc.
  og:title: SEO 元数据标题
  ---
  ```
</CodeBlock>

### 特殊字符

前置事项使用 YAML 语法，但值也会作为 MDX 处理。某些字符需要加引号，而其他字符需要反斜杠转义。

| 字符                      | 解决方案        | 示例                              |
| ----------------------- | ----------- | ------------------------------- |
| `:` `#` `&` `*` `!` `%` | 用引号包装       | `title: "OAuth: A guide"`       |
| `{` `}` `<` `>`         | 用 `\` 转义    | `title: "Using \<Callout\>"`    |
| `"` `'`                 | 使用相反样式或 `\` | `title: 'The "best" practices'` |

### 常见错误

#### 解析前置事项失败

如果 `fern check` 报告 `Failed to parse frontmatter`，则 `---` 标记之间的 [YAML](#frontmatter-syntax) 无效。最常见的原因是未加引号的值包含 [特殊字符](#special-characters)。将值用引号包装或转义字符并重新运行 `fern check`。

## 标题

<ParamField path="title" type="string" required={false} default="docs.yml 中的页面名称">
  设置页面的 [`<title>` 元素](https://web.dev/learn/html/document-structure#document_title)。这出现在浏览器标签、书签和搜索结果中。
</ParamField>

页面标题可以通过两种方式设置：

1. 在页面的前置事项中：

```mdx title="welcome.mdx"
---
title: 欢迎使用我们的文档
---
```

2. 从 docs.yml 中的页面名称（如果没有设置前置事项标题则使用）：

```yaml title="docs.yml"
title: Fern | Documentation  # 站点范围标题后缀
navigation:
  - page: Welcome          # 这成为页面标题
    path: ./pages/welcome.mdx
```

最终标题将包含站点范围后缀。例如：

* 使用前置事项："欢迎使用我们的文档 - Fern | Documentation"
* 不使用前置事项："Welcome - Fern | Documentation"

## 侧边栏标题

<ParamField path="sidebar-title" type="string" required={false} default="docs.yml 中的页面名称">
  设置在侧边栏导航中显示的标题。这优先于 `docs.yml` 中定义的侧边栏标题。当您希望在保持描述性页面标题的同时使用较短的导航标签时使用此选项。
</ParamField>

侧边栏标题可以通过两种方式设置：

1. 在页面的前置事项中：

```mdx title="authentication.mdx"
---
title: 身份验证入门 # 浏览器标签和页面标题
sidebar-title: 身份验证 # 仅用于侧边栏的简短版本
---
```

2. 从 docs.yml 中的页面名称（如果没有设置前置事项 `sidebar-title` 则使用）：

```yaml title="docs.yml" 
navigation:
  - page: Authentication guide # 如果没有前置事项覆盖则显示在侧边栏中
    path: ./pages/authentication.mdx
```

## 副标题

<ParamField path="subtitle" type="string" required={false}>
  在页面上渲染为副标题。如果未设置 `description`，则 `subtitle` 也用作元描述标签和 [`llms.txt` 和 `llms-full.txt`](/learn/docs/ai-features/llms-txt#page-descriptions) 中。
</ParamField>

例如，滚动到您现在正在访问的页面顶部，您将看到副标题"使用前置事项设置标题、描述、路径、布局和可见性"。

## 最后更新

<ParamField path="last-updated" type="string" required={false}>
  在页面页脚显示"最后更新"时间戳。使用此选项向读者显示内容最后修改的时间。该值按原样显示，因此您可以使用任何您喜欢的日期格式。

  此字段与您的 [sitemap](/learn/docs/seo/overview#what-fern-handles-automatically) 中的时间戳分开，后者由系统自动管理并仅供搜索引擎使用。
</ParamField>

<CodeBlock title="最后更新示例">
  ```mdx
  ---
  title: API 参考
  last-updated: 2025年12月9日
  ---
  ```
</CodeBlock>

<Tip>
  想要在 MDX 文件更改时自动更新 `last-updated` 字段？请参见 [自动更新最后更新日期](/learn/docs/developer-tools/auto-update-last-updated-dates) 设置 GitHub Action 工作流程。
</Tip>

## 路径

<ParamField path="slug" type="string" required={false}>
  覆盖页面的完整 URL 路径，从文档站点的根目录开始。这优先于在 docs.yml 中定义的任何路径。
</ParamField>

例如，如果您在前置事项中设置 `slug: email`，页面将在 `/email` 可用，无论其在导航结构中的位置如何。

有两种方式设置页面的 URL 路径：

1. 在 docs.yml 中使用 `slug`，这相对于页面在导航中的位置：

<CodeBlock title="docs.yml">
  ```yaml
  navigation:
    - tab: overview
      layout:
        - section: Support
          contents:
            - page: Email Us
              path: ./pages/email-us.mdx
              slug: email  # 结果为 /overview/support/email
  ```
</CodeBlock>

2. 在前置事项中使用 `slug`，这会覆盖一切并从根目录设置绝对路径：

<CodeBlock title="email-us.mdx">
  ```mdx
  ---
  slug: email  # 结果为 /email（忽略导航结构）
  ---
  ```
</CodeBlock>

关键区别是：

* docs.yml 中的 slug 相对于页面在导航结构中的位置
* 前置事项中的 slug 是绝对的，完全忽略导航结构

## 元描述

<ParamField path="description" type="string" required={false}>
  设置页面的 [元描述](https://web.dev/learn/html/metadata#description)。与页面标题一样，元描述对 SEO 很重要。它影响搜索引擎在搜索结果片段中显示的关于您页面的文本。它还可以影响搜索引擎的索引和排名。有关更多信息，请参见 [Google 的元描述指南](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions)。描述还用于 [`llms.txt` 和 `llms-full.txt`](/learn/docs/ai-features/llms-txt#page-descriptions)。
</ParamField>

<CodeBlock title="元描述示例">
  ```mdx
  ---
  title: API 身份验证
  description: 了解如何使用 API 密钥、OAuth 2.0 或 JWT 令牌来验证您的 API 请求。包含多种语言的代码示例和安全最佳实践。
  ---
  ```
</CodeBlock>

## 编辑此页面

<ParamField path="edit-this-page-url" type="string" required={false}>
  提供 GitHub 中源 `.md` 或 `.mdx` 文件的绝对链接。Fern 使用它在页面上添加"编辑此页面"链接，您的文档用户可以使用它来建议更正或添加内容。您也可以全局配置这个而不是逐页配置 - 请参见 [全局配置](/learn/docs/configuration/site-level-settings#edit-this-page-configuration)。

  此 URL 适用于两种 [启动模式](/learn/docs/user-feedback#edit-this-page)。使用 `launch: github` 时，它是编辑按钮的主要链接。使用 `launch: dashboard` 时，它作为备用传递，以便用户也可以从仪表板屏幕导航到 GitHub 上的源。
</ParamField>

<CodeBlock title="编辑此页面 URL 示例">
  ```mdx
  ---
  title: API 参考
  edit-this-page-url: https://github.com/your-org/docs/blob/main/content/api-reference.mdx
  ---
  ```
</CodeBlock>

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/7ad2b2c03552e0e1c18247a9569589cc1a5c1254681fd68acd0378509aed7afd/products/docs/pages/navigation/edit-this-page.png" alt="编辑此页面功能" />
</Frame>

## 元图片

<ParamField path="image" type="string" required={false}>
  使用指向在线托管图片的绝对 URL 为页面配置 OpenGraph 图片元数据。当您的文档链接在社交媒体平台上分享时，此图片会出现，使用 [OpenGraph](https://ogp.me/) 元数据协议。有关更多信息，请参见 [web.dev 的 OpenGraph 说明](https://web.dev/learn/html/metadata#open_graph)。
</ParamField>

## 目录

### 隐藏目录

<ParamField path="hide-toc" type="boolean" required={false} default={false}>
  控制页面右侧目录功能的条件渲染。设置为 `true` 以禁用此功能。
</ParamField>

<CodeBlock title="隐藏目录示例">
  ```mdx
  ---
  title: 首页
  hide-toc: true
  ---
  ```
</CodeBlock>

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/c8c8f24d5d058f1e496ae36cf193dd65e83e0193413e3107c0e35d3cc2cfb354/products/docs/pages/navigation/table-of-contents.png" alt="目录功能" />
</Frame>

当目录被隐藏时，Fern 默认会将页面内容居中。要控制页面的布局，请参见 [布局文档](#layout)。

### 最大深度

<ParamField path="max-toc-depth" type="number" required={false}>
  设置目录的最大深度。例如，值为 `3` 将只在目录中显示 `<h1>`、`<h2>` 和 `<h3>` 标题。
</ParamField>

<CodeBlock title="目录最大深度示例">
  ```mdx
  ---
  title: 示例页面
  max-toc-depth: 3
  ---
  ```
</CodeBlock>

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/147bd164a594901141798a2293e8c280012a0a5ae7e39d6bc125b9ead426f81a/products/docs/pages/navigation/max-toc.png" alt="目录最大深度" />
</Frame>

## 导航链接

<ParamField path="hide-nav-links" type="boolean" required={false} default={false}>
  控制页面底部导航链接（上一页、下一页）的条件渲染。设置为 true 以禁用此功能。

  这可以在 [全局配置](/learn/docs/configuration/site-level-settings#layout-configuration) 中全局设置。
</ParamField>

<CodeBlock title="隐藏导航链接示例">
  ```mdx
  ---
  title: 独立指南
  hide-nav-links: true
  ---
  ```
</CodeBlock>

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/589f6bff88be20aeecd2dfcaa48bbbaf455df2b1eb822fc6ee287187c7f74dc9/products/docs/pages/navigation/nav-link.png" alt="导航链接功能" />
</Frame>

## 页面反馈

<ParamField path="hide-feedback" type="boolean" required={false} default={false}>
  控制页面底部页面反馈表单的条件渲染。设置为 true 以禁用此功能。

  这可以在 [全局配置](/learn/docs/configuration/site-level-settings#layout-configuration) 中全局设置。
</ParamField>

<CodeBlock title="隐藏反馈示例">
  ```mdx
  ---
  title: API 状态页面
  hide-feedback: true
  ---
  ```
</CodeBlock>

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/6773a2db4328b6a14cbabee0d512d8d5c798b74a1b5e3a51d8517a38b6786d30/products/docs/pages/navigation/on-page-feedback.png" alt="留下反馈功能" />
</Frame>

## 页面操作

<ParamField path="hide-page-actions" type="boolean" required={false} default={false}>
  控制页面操作按钮（复制页面、查看为 Markdown、Ask AI、ChatGPT、Claude、Claude Code、Cursor）的条件渲染。设置为 true 以关闭单个页面的页面操作。

  或者，在您的 `docs.yml` 文件中为 [整个站点配置页面操作](/learn/docs/configuration/site-level-settings#page-actions-configuration)。
</ParamField>

<CodeBlock title="docs/getting-started/overview.mdx">
  ```mdx
  ---
  title: 概述
  hide-page-actions: true
  ---
  ```
</CodeBlock>

## 页面标志

<ParamField path="logo" type="object" required={false}>
  覆盖页面的站点范围标志。使用绝对 URL 为浅色和深色模式指定不同的标志。
</ParamField>

<CodeBlock title="index.mdx 标志示例">
  ```mdx
  ---
  logo:
    light: https://link-to-image.com/image-light-mode.png
    dark: https://link-to-image.com/image-dark-mode.png
  ---
  ```
</CodeBlock>

<Info>
  目前，此字段不支持相对路径。
</Info>

## 布局

<ParamField path="layout" type="string" required={false} default="guide">
  设置页面布局。可用选项：

  * `guide`：默认文档布局，右侧有目录。适用于教程、操作指南和任何受益于通过章节轻松导航的内容。

  * `overview`：更宽的布局（比 `guide` 宽50%），带有目录和导航侧边栏。非常适合需要更多水平空间同时保持导航的首页和章节概述。

  * `reference`：为 API 或 SDK 参考优化的全宽布局。始终隐藏目录，因此您可以添加另一列，如代码示例。导航侧边栏保持可见。

  * `page`：无干扰的全屏布局，隐藏目录和导航侧边栏。最适合受益于专注阅读体验的独立内容。

  * `custom`：空白画布布局，移除所有默认样式约束。隐藏目录和导航侧边栏，允许完全控制页面布局。
</ParamField>

## SEO 元数据

<Note title="希望在整个站点设置元数据？">
  [在 `docs.yml` 文件中使用元数据字段](/learn/docs/configuration/site-level-settings#seo-metadata-configuration)。
</Note>

<Info>
  只有记录的 SEO 字段会作为元标签添加到 HTML `<head>` 中。自定义前置事项字段不会自动出现在您的页面元数据中。要添加自定义元数据，请使用 [自定义 JavaScript](/learn/docs/customization/custom-css-js#custom-javascript)。
</Info>

<CodeBlock title="plantstore-quickstart.mdx">
  ```mdx
  ---
  title: PlantStore API 快速开始
  headline: "PlantStore API 入门 | 开发者文档"
  keywords: plants, garden, nursery
  canonical-url: https://docs.plantstore.dev/welcome
  og:site_name: PlantStore 开发者文档
  og:title: "PlantStore API 快速开始指南"
  og:description: "了解如何集成 PlantStore 的 API 来管理植物库存、处理订单和跟踪运输。包含完整的代码示例。"
  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
  ---
  ```
</CodeBlock>

<AccordionGroup>
  <Accordion title="文档属性">
    <ParamField path="headline" type="string" required={false}>
      当设置时，文档头部的 `<title />` 标签将使用此值而不是 `title` 属性。此属性更改搜索引擎在抓取此页面时看到的标题，可用于解决 SEO 报告中的重复标题问题。
    </ParamField>

    <ParamField path="canonical-url" type="string" required={false} toc={true}>
      覆盖此页面的规范 URL。必须是包含协议的完整 URL（即 `https://buildwithfern.com/learn/docs/content/frontmatter`）
    </ParamField>

    <ParamField path="keywords" type="string" required={false}>
      与页面内容相关的关键词逗号分隔字符串（即 `plants, garden, nursery`）。这些关键词帮助搜索引擎理解页面主题并有助于搜索排名。使用用户在寻找页面内容时可能搜索的特定相关术语。

      此字段只接受逗号分隔的字符串，而不是括号数组。
    </ParamField>
  </Accordion>

  <Accordion title="OpenGraph 属性">
    <ParamField path="og:site_name" type="string" required={false}>
      您的网站在内容分享时应出现的名称。
    </ParamField>

    <ParamField path="og:title" type="string" required={false}>
      您的页面在内容分享时应出现的标题。
    </ParamField>

    <ParamField path="og:description" type="string" required={false}>
      您的页面在内容分享时应出现的描述。
    </ParamField>

    <ParamField path="og:url" type="string" required={false}>
      您页面的 URL。
    </ParamField>

    <ParamField path="og:image" type="string" required={false}>
      内容分享时将显示的图片的 URL 或标识符。
    </ParamField>

    <ParamField path="og:image:width" type="number" required={false}>
      图片的宽度（像素）。
    </ParamField>

    <ParamField path="og:image:height" type="number" required={false}>
      图片的高度（像素）。
    </ParamField>

    <ParamField path="og:locale" type="string" required={false}>
      页面的语言环境，通常采用 `language_TERRITORY` 格式（例如，`en_US`）。
    </ParamField>

    <ParamField path="og:logo" type="string" required={false}>
      内容分享时将显示的您网站标志图片的 URL 或标识符。
    </ParamField>
  </Accordion>

  <Accordion title="Twitter 属性">
    <ParamField path="twitter:title" type="string" required={false}>
      您的页面在推文中应出现的标题。
    </ParamField>

    <ParamField path="twitter:description" type="string" required={false}>
      您的页面在推文中应出现的描述。
    </ParamField>

    <ParamField path="twitter:handle" type="string" required={false}>
      页面创建者或站点的 Twitter 用户名。
    </ParamField>

    <ParamField path="twitter:image" type="string" required={false}>
      推文中将显示的图片的 URL 或标识符。
    </ParamField>

    <ParamField path="twitter:site" type="string" required={false}>
      您的网站在推文中应出现的名称。
    </ParamField>

    <ParamField path="twitter:url" type="string" required={false}>
      您页面的 URL。
    </ParamField>

    <ParamField path="twitter:card" type="string" required={false}>
      在 Twitter 上分享使用的卡片类型。选项：`summary`、`summary_large_image`、`app`、`player`
    </ParamField>
  </Accordion>

  <Accordion title="索引属性">
    <ParamField path="noindex" type="boolean" required={false} default={false} toc={true}>
      如果设置为 `true`，页面将不会被搜索引擎索引，并将从 [llms.txt](/learn/docs/ai-features/llms-txt) 端点中排除。
    </ParamField>

    <ParamField path="nofollow" type="boolean" required={false} default={false} toc={true}>
      如果设置为 `true`，搜索引擎将不会跟随页面上存在的任何链接。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 可用性

<ParamField path="availability" type="string" required={false}>
  在页面上显示可用性标识。当在前置事项中设置时，它覆盖在 [导航中定义的任何可用性](/learn/docs/configuration/navigation#availability)（`docs.yml`）。有效值为：`stable`、`generally-available`、`in-development`、`pre-release`、`deprecated` 或 `beta`。
</ParamField>

<CodeBlock title="fern/docs/pages/getting-started/feature.mdx">
  ```mdx
  ---
  title: 新功能
  availability: beta
  ---
  ```
</CodeBlock>

当您想要为单个页面设置可用性而不修改 `docs.yml` 导航配置，或当您需要覆盖从父级部分或文件夹继承的可用性时，这很有用。

## 更新日志标签

<ParamField path="tags" type="array of strings" required={false}>
  仅用于 [更新日志页面](/docs/configuration/changelogs)。标签允许用户按特定类别过滤更新日志条目。在前置事项中将标签定义为字符串数组。
</ParamField>

<CodeBlock title="fern/openapi/changelog/2024-07-31.mdx">
  ```mdx
  ---
  tags: ["plants-api", "breaking-change", "inventory-management"]
  ---

  ## Summary

  In the latest release, we've added endpoints to create a new Plant.

  ### What's new?

  New endpoints:

  - `POST /plant` add a new plant to inventory.

  New object schemas:

  - `CreatePlantRequest`

  <Note> Have questions? Reach out to your local botanist. </Note>
  ```
</CodeBlock>