Front Matter 配置

title

  • Type: string

页面的标题。默认情况下,页面的 h1 标题将用作 HTML 文档的标题。但是如果你想使用不同的标题,你可以使用 Front Matter 来指定页面的标题。例如:

---
title: 我的主页
---

description

  • Type: string

页面的自定义描述。例如:

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

pageType

  • Type: 'home' | 'doc' | 'custom' | 'blank' | '404'
  • Default: 'doc'

页面的类型。默认情况下,页面类型为doc。但是如果你想使用不同的页面类型,你可以使用pageType这个 Front Matter 字段来指定页面类型。例如:

---
pageType: home
---

各个pageType配置的含义如下:

  • home: 首页,包含顶部导航栏和首页的布局内容。
  • doc: 文档页,包含顶部导航栏、左边侧边栏、正文内容和右侧的大纲栏。
  • custom: 自定义页面,包含顶部导航栏和自定义的内容。
  • blank: 也属于自定义页面,但是不包含顶部导航栏
  • 404: 404 页面

titleSuffix

  • Type: string

设置页面标题的后缀。未设置 titleSuffix 时,默认使用站点的 title 作为后缀。

---
titleSuffix: '基于 Rspack 的静态站点生成器'
---

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

---
titleSuffix: '| 基于 Rspack 的静态站点生成器'
---

hero

  • Type: Object

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

interface Hero {
  name: string;
  text: string;
  tagline: string;
  image?: {
    src: 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

  • Type: Array
  • Default: []

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 来配置:

---
sidebar: false
---

outline

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

---
outline: false
---

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

---
footer: false
---

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

---
navbar: false
---

overviewHeaders

  • Type: number[]
  • Default: [2]

在预览页中展示的标题级别。默认情况下,展示的标题为 h2。但是如果你想展示不同的标题级别,你可以使用 overviewHeaders 这个 Front Matter 字段来指定。例如:

---
overviewHeaders: []
---

或者

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