Front Matter 配置
title
页面的标题。默认情况下，页面的 h1 标题将用作 HTML 文档的标题。但是如果你想使用不同的标题，你可以使用 Front Matter 来指定页面的标题。例如：
description
页面的自定义描述。例如：
---
description: 这是我的主页
---
pageType
- Type:
'home' | 'doc' | 'custom' | 'blank' | '404'
- Default:
'doc'
页面的类型。默认情况下，页面类型为doc。但是如果你想使用不同的页面类型，你可以使用pageType这个 Front Matter 字段来指定页面类型。例如：
各个pageType配置的含义如下：
home: 首页，包含顶部导航栏和首页的布局内容。doc: 文档页，包含顶部导航栏、左边侧边栏、正文内容和右侧的大纲栏。custom: 自定义页面，包含顶部导航栏和自定义的内容。blank: 也属于自定义页面，但是不包含顶部导航栏。404: 404 页面。
titleSuffix
设置页面标题的后缀。未设置 titleSuffix 时，默认使用站点的 title 作为后缀。
---
titleSuffix: '基于 Rspack 的静态站点生成器'
---
标题与后缀之间默认使用 - 作为分隔符，你也可以使用 | 进行分隔：
---
titleSuffix: '| 基于 Rspack 的静态站点生成器'
---
head
- Type:
[string, Record<string, string>][]
设置为当前页面注入的额外 head 标签，它们将附加在 Rspress 全局注入的 head 标签之后。
例如，你可以使用这些 headers 为 Open Graph 指定自定义元标签。
---
head:
- - meta
- name: og:title
content: The Rock
- - meta
- name: og:url
content: https://www.imdb.com/title/tt0117500/
- - meta
- name: og:image
content: https://ia.media-imdb.com/images/rock.jpg
# - - [htmlTag]
# - [attributeName]: [attributeValue]
# [attributeName]: [attributeValue]
---
Note
确保正确定义 head 的标签（tag）名称及其属性（attribute）名称。
对于包含连字符（-）的标签和属性名称，请使用驼峰式大小写格式。
例如，http-equiv="refresh" 应定义为 httpEquiv: refresh。
这是因为 headers 在底层由 React 和 react-helmet-async 处理。
hero
home 页面的 hero 配置。它有以下类型：
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：
---
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 的 | 符号来手动控制换行：
---
pageType: home
hero:
name: Rspress
text: |
文档工程
解决方案
或者你也可以用 HTML 来指定页面的 hero config：
---
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
home 页面的功能配置。它有以下类型：
interface Feature {
title: string;
details: string;
icon: string;
// 卡片栅格的长度，目前仅支持[3, 4, 6]
span?: number;
// feature 卡片跳转链接，选填
link?: string;
}
export type Features = Feature[];
例如，你可以使用以下内容来指定 home 页面的 features 配置：
---
pageType: home
features:
- title: 'MDX: 使用灵活语法编写内容'
details: MDX 是一种强大的内容编写方式，你可以在 Markdown 中使用 React 组件。
icon: 📦
- title: '功能丰富: 一站式解决方案'
details: 对全文搜索、国际化等常见功能可以做到开箱即用。
icon: 🎨
- title: '扩展性强: 提供多种自定义能力'
details: 通过其扩展机制，你可以轻松的扩展主题 UI 和构建能力。
icon: 🚀
---
是否展示左侧的目录栏。默认情况下，doc 页面会展示左侧的目录栏。但是如果你想隐藏左侧的目录栏，你可以使用以下 Front Matter 来配置：
outline
是否展示右侧的大纲栏。默认情况下，doc 页面会展示右侧的大纲栏。你可以通过下面的配置来隐藏大纲栏：
是否展示文档底部的组件(如上一页/下一页)。默认情况下，doc 页面会展示底部的 footer。你可以通过下面的配置来隐藏 footer：
navbar
是否展示顶部导航栏。默认情况下，所有页面都会展示顶部导航栏。但是如果你想隐藏顶部导航栏，你可以使用以下 Front Matter 来配置：
- Type:
number[]
- Default:
[2]
在预览页中展示的标题级别。默认情况下，展示的标题为 h2。但是如果你想展示不同的标题级别，你可以使用 overviewHeaders 这个 Front Matter 字段来指定。例如：
---
overviewHeaders: []
---
或者
---
overviewHeaders: [2, 3]
---
context
配置后，在生成侧边栏时会在所在的 DOM 节点添加 data-context 属性，值为配置的值。
foo.mdx
---
context: 'context-foo'
---
bar.mdx
---
context: 'context-bar'
---
最终生成的侧边栏的 DOM 结构缩略如下：
<div class="rspress-sidebar-group">
<div data-context="context-foo"></div>
<div data-context="context-bar"></div>
</div>
