> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.

# Front matter 配置

这篇文档介绍了如何使用 front matter 来配置页面的各种属性，包括标题、描述、页面类型、导航栏等。

查看 [Front matter](https://rspress.rs/zh/guide/use-mdx/frontmatter.md) 了解什么是 front matter 以及如何使用它，查看 [useFrontmatter](https://rspress.rs/zh/ui/hooks/use-frontmatter.md) 了解如何在代码中获取 front matter。

## title

- **类型**： `string`

页面的标题。默认情况下，页面的 h1 标题将用作 HTML 文档的标题。如果你想使用不同的标题，你可以使用 front matter 来指定页面的标题。例如：

```mdx
---
title: 我的主页
---

这是我的**主页内容**。
```

它等价于：

```mdx
# 我的主页

这是我的**主页内容**。
```

## description

- **类型**： `string`

页面的自定义描述，会在页面中生成 `<meta name="description" content="..." />` 标签用于 SEO 优化。

默认情况下，Rspress 会提取 `h1` 标题下方第一段有内容的段落作为描述（参见 [`markdown.extractDescription`](https://rspress.rs/zh/api/config/config-build.md#markdownextractdescription)）。如果提取结果不满足需求，可以使用此字段覆盖。详情请参阅[自定义 Head 标签 - description 的获取方式](https://rspress.rs/zh/guide/advanced/custom-head.md#description-%E7%9A%84%E8%8E%B7%E5%8F%96%E6%96%B9%E5%BC%8F)。

```yaml
---
description: 这是我的主页
---
```

## pageType

- **类型**： `'home' | 'doc' | 'doc-wide' | 'custom' | 'blank' | '404'`
- **默认值**: `'doc'`

页面的类型。默认情况下，页面类型为`doc`。但是如果你想使用不同的页面类型，你可以使用 `pageType` 这个 front matter 字段来指定页面类型。例如：

```yaml
---
pageType: home
---
```

各个`pageType`配置的含义如下：

- `home`: **首页**，包含顶部导航栏和首页的布局内容。
- `doc`: **文档页**，包含顶部导航栏、左边侧边栏、正文内容和右侧的大纲栏。
- `doc-wide`: **宽屏文档页**，配合 `outline: false` 和 `sidebar: false` 设置时，正文内容会自动占据更宽的屏幕空间。
- `custom`: **自定义页面**，包含顶部导航栏和自定义的内容。
- `blank`: 也属于**自定义页面**，但是不包含`顶部导航栏`。
- `404`: **404 页面**。

## titleSuffix

- **类型**： `string`

设置页面标题的后缀。未设置 `titleSuffix` 时，默认使用站点的 [title](https://rspress.rs/zh/api/config/config-basic.md#title) 作为后缀。

```yaml
---
titleSuffix: '基于 Rsbuild 的静态站点生成器'
---
```

标题与后缀之间默认使用 `-` 作为分隔符，你也可以使用 `|` 进行分隔：

```yaml
---
titleSuffix: '| 基于 Rsbuild 的静态站点生成器'
---
```

## sidebar

- **类型**： `boolean | 'placeholder'`
- **默认值**： `true`

是否展示左侧的目录栏。默认情况下，`doc` 页面会展示左侧的目录栏。但是如果你想隐藏左侧的目录栏，你可以使用以下 front matter 来配置：

```yaml
---
sidebar: false
---
```

:::tip 提示
`sidebar: false` 会隐藏侧边栏，并在左侧保留 `12vw` 的占位，使正文内容在大屏下保持视觉居中。如果你想让正文内容占据更宽的屏幕空间，可以使用 [`pageType: doc-wide`](#pagetype) 配合 `sidebar: false`：

```yaml
---
pageType: doc-wide
sidebar: false
---
```

这样正文内容区域会自动扩展，占据原本侧边栏的空间。

如果你想保留左侧 sidebar 的空白，可以使用 `sidebar: 'placeholder'`：

```yaml
---
sidebar: 'placeholder'
---
```

:::

## outline

是否展示右侧的大纲栏。默认情况下，`doc` 页面会展示右侧的大纲栏。你可以通过下面的配置来隐藏大纲栏：

```yaml
---
outline: false
---
```

:::tip 提示
`outline: false` 仅隐藏大纲栏，但原本大纲栏占据的空间仍然保留。如果你想让正文内容占据更宽的屏幕空间，可以使用 [`pageType: doc-wide`](#pagetype) 配合 `outline: false`：

```yaml
---
pageType: doc-wide
outline: false
---
```

这样正文内容区域会自动扩展，占据原本大纲栏的空间。
:::

## footer

是否展示文档底部的组件（如上一页/下一页）。默认情况下，`doc` 页面会展示底部的 footer。你可以通过下面的配置来隐藏 footer：

```yaml
---
footer: false
---
```

## navbar

是否展示顶部导航栏。默认情况下，所有页面都会展示顶部导航栏。但是如果你想隐藏顶部导航栏，你可以使用以下 front matter 来配置：

```yaml
---
navbar: false
---
```

## icon


[新增于 v2.0.19](https://github.com/web-infra-dev/rspress/releases/tag/v2.0.19)

- **类型**： `string`

设置自动生成的侧边栏中显示在页面标题之前的图标。使用本地图片时，应将资源放在 `public` 目录中，并通过绝对路径引用：

```yaml
---
icon: /icon.png
---
```

此外还支持内联 SVG 字符串、emoji、外链和 data URL。如果同一个文件项同时在 frontmatter 和 `_meta.json` 中配置了 `icon`，则以 frontmatter 的值为准。

更多示例请参考[侧边栏图标和标签](https://rspress.rs/zh/guide/basic/auto-nav-sidebar.md#%E4%BE%A7%E8%BE%B9%E6%A0%8F%E5%9B%BE%E6%A0%87%E5%92%8C%E6%A0%87%E7%AD%BE)。

## context

- **类型**： `string`

配置后，在生成侧边栏时会在所在的 DOM 节点添加 `data-context` 属性，值为配置的值。

```yaml title="foo.mdx"
---
context: 'context-foo'
---
```

```yaml title="bar.mdx"
---
context: 'context-bar'
---
```

最终生成的侧边栏的 DOM 结构缩略如下：

```html
<div class="rspress-sidebar-group">
  <div className="rspress-sidebar-item" data-context="context-foo"></div>
  <div className="rspress-sidebar-item" data-context="context-bar"></div>
</div>
```

## search

- **类型**： `boolean`
- **默认值**： `true`

是否将当前页面加入内置搜索索引。默认情况下，每个 `doc` 页面都会被加入全文搜索索引。如果想从搜索结果中排除某个页面，可以将 `search` 设置为 `false`：

```yaml
---
search: false
---
```

该配置只影响内置搜索。设置了 `pageType: home` 的页面无论是否配置该字段，都会从搜索索引中排除。

## head

- **类型**： `[string, Record<string, string>][]`

设置为当前页面注入的额外 head 标签，它们将附加在 Rspress 全局注入的 head 标签之后。

例如，你可以使用这些 headers 为 [Open Graph](https://ogp.me/) 指定自定义元标签。

```yaml
---
head:
  - - meta
    - property: og:url
      content: https://example.com/foo/
  - - meta
    - property: og:image
      content: https://example.com/bar.jpg
# - - [htmlTag]
#   - [attributeName]: [attributeValue]
#     [attributeName]: [attributeValue]
---
```

生成的 head 标签如下：

```html
<head>
  <meta property="og:url" content="https://example.com/foo/" />
  <meta property="og:image" content="https://example.com/bar.jpg" />
</head>
```

## Overview 页相关

以下配置与 [Overview 页](https://rspress.rs/zh/guide/advanced/overview-page.md) 功能相关。

### overview

- **类型**： `boolean`
- **默认值**: `false`

在文档页面中启用 Overview 页功能。如果设置为 `true`，意味着当前页面是 [Overview 页](https://rspress.rs/zh/guide/advanced/overview-page.md)。例如：

```yaml
---
overview: true
---
```

### overviewHeaders

- **类型**： `number[]`
- **默认值**: `[2]`

在 Overview 页中展示的标题级别。默认情况下，展示的标题为 h2。但是如果你想展示不同的标题级别，你可以使用 `overviewHeaders` 这个 front matter 字段来指定。例如：

```yaml
---
overview: true
overviewHeaders: []
---
```

或者

```yaml
---
overviewHeaders: [2, 3]
---
```

## 首页相关

以下配置与 [首页](https://rspress.rs/zh/guide/basic/home-page.md) 功能相关。

### hero

- **类型**： `Object`

`home` 页面的 hero 配置。它有以下类型：

```ts
interface Hero {
  name: string;
  text: string;
  tagline: string;
  image?: {
    src: string | { dark: string; light: string };
    alt: string;
    /**
     * `srcset` 和 `sizes` 同 `<img>` 的同名属性，取值请参考 https://mdn.io/srcset。
     * 值为数组时，rspress 将使用逗号将其合并为字符串。
     **/
    srcset?: string | string[];
    sizes?: string | string[];
  };
  actions: {
    text: string;
    link: string;
    theme: 'brand' | 'alt';
  }[];
}
```

例如，你可以使用以下 front matter 来指定页面的 hero config：

```yaml
---
pageType: home

hero:
  name: Rspress
  text: 文档工程解决方案
  tagline: 现代化文档开发技术栈
  actions:
    - theme: brand
      text: 介绍
      link: /zh/guide/introduction
    - theme: alt
      text: 快速开始
      link: /zh/guide/getting-started
---
```

在设置 `hero.text` 时，你可以使用 YAML 的 `|` 符号来手动控制换行：

```yaml
---
pageType: home

hero:
  name: Rspress
  text: |
    文档工程
    解决方案
```

或者你也可以用 `HTML` 来指定页面的 hero config：

```yaml
---
pageType: home

hero:
  name: <span class="hero-name">Rspress</span>
  text: <span class="hero-text">文档工程解决方案</span>
  tagline: <span class="hero-tagline">现代化文档开发技术栈</span>
  actions:
    - theme: brand
      text: <span class="hero-actions-text">介绍</span>
      link: /zh/guide/introduction
    - theme: alt
      text: <span class="hero-actions-text">快速开始</span>
      link: /zh/guide/getting-started
---
```

### features

- **类型**： `Array`
- **默认值**: `[]`

`home` 页面的功能配置。它有以下类型：

```ts
interface Feature {
  title: string;
  details: string;
  icon: string;
  // 卡片栅格的长度，目前仅支持[3, 4, 6]
  span?: number;
  // feature 卡片跳转链接，选填
  link?: string;
}

export type Features = Feature[];
```

例如，你可以使用以下内容来指定 `home` 页面的 features 配置：

```yaml
---
pageType: home

features:
  - title: 'MDX: 使用灵活语法编写内容'
    details: MDX 是一种强大的内容编写方式，你可以在 Markdown 中使用 React 组件。
    icon: 📦
  - title: '功能丰富: 一站式解决方案'
    details: 对全文搜索、国际化等常见功能可以做到开箱即用。
    icon: 🎨
  - title: '扩展性强: 提供多种自定义能力'
    details: 通过其扩展机制，你可以轻松地扩展主题 UI 和构建能力。
    icon: 🚀
---
```