#Frontmatter config

This page explains how to configure page-level properties with frontmatter, including title, description, page type, and navbar visibility.

See Frontmatter for the frontmatter syntax, and useFrontmatter for accessing frontmatter in code.

#title

• Type: string

The page title. By default, Rspress uses the page's H1 heading as the HTML document title. To use a different title, set it in frontmatter:

---
title: My Homepage
---

This is my **homepage content**.

It is equivalent to:

# My homepage

This is my **homepage content**.

#description

• Type: string

A custom description for the page. Rspress uses it to generate a <meta name="description" content="..." /> tag on the page for SEO optimization.

By default, Rspress extracts the first contentful paragraph below the h1 heading as the description (see markdown.extractDescription). If the extracted result does not meet your needs, you can use this field to override it. For more details, see Custom Head - How description is determined.

---
description: This is my homepage
---

#pageType

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

The page type. The default is doc. To use a different page type, set the pageType frontmatter field:

---
pageType: home
---

The meaning of each pageType config is as follows:

• home: Homepage, including the top navbar and homepage layout content.
• doc: Doc page, including the top navbar, left sidebar, body content, and right-side outline.
• doc-wide: Wide doc page, where the main content can occupy a wider area when outline: false and sidebar: false are used together.
• custom: Custom page, including the top navbar and custom content.
• blank: Also a custom page, but without the top navbar.
• 404: Not found page.

#titleSuffix

• Type: string

Set the suffix of the page title. When titleSuffix is not set, the site's title is used as the suffix by default.

---
titleSuffix: 'Rsbuild-based Static Site Generator'
---

The default separator between the title and suffix is -. You can also use |:

---
titleSuffix: '| Rsbuild-based Static Site Generator'
---

#sidebar

• Type: boolean | 'placeholder'
• Default: true

Controls whether the left sidebar is shown. By default, doc pages display the left sidebar. To hide it, use the following frontmatter:

---
sidebar: false
---

---
pageType: doc-wide
sidebar: false
---

---
sidebar: 'placeholder'
---

#outline

Controls whether the right-side outline is shown. By default, doc pages display the right-side outline. To hide it, use:

---
outline: false
---

---
pageType: doc-wide
outline: false
---

#footer

Controls whether footer components, such as previous/next page links, are shown at the bottom of the page. By default, doc pages display the footer. To hide it, use:

---
footer: false
---

#navbar

Controls whether the top navbar is shown. By default, all pages display the top navbar. To hide it, use:

---
navbar: false
---

#context

• Type: string

When configured, Rspress adds a data-context attribute with this value to the generated sidebar DOM node.

---
context: 'context-foo'
---

---
context: 'context-bar'
---

The DOM structure of the final generated sidebar is abbreviated as follows:

<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

• Type: boolean
• Default: true

Whether to include the current page in the built-in search index. By default every doc page is indexed for full-text search. If you want to exclude a specific page from the search results, set search to false:

---
search: false
---

This only affects the built-in search. Pages with pageType: home are always excluded from the search index regardless of this field.

#head

• Type: [string, Record<string, string>][]

Specify extra head tags to be injected for the current page. They will be appended after the head tags injected by Rspress globally.

For example, you can use these headers to specify custom meta tags for Open Graph.

---
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]
---

The generated head tags are as follows:

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

#Overview page related

The following configurations are related to the Overview Page feature.

#overview

• Type: boolean
• Default: false

Enables the overview page feature for the current doc page. When set to true, the current page becomes an Overview Page. For example:

---
overview: true
---

#overviewHeaders

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

Heading levels to show on the overview page. By default, H2 headings are shown. To display other heading levels, set the overviewHeaders frontmatter field:

---
overview: true
overviewHeaders: []
---

Or

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

#Homepage related

The following options are related to the homepage feature.

#hero

• Type: Object

Hero configuration for the home page. It has the following type:

interface Hero {
  name: string;
  text: string;
  tagline: string;
  image?: {
    src: string | { dark: string; light: string };
    alt: string;
    /**
     * `srcset` and `sizes` are `<img>` attributes. See https://mdn.io/srcset for usage.
     * When the value is an array, Rspress joins array members with commas.
     **/
    srcset?: string | string[];
    sizes?: string | string[];
  };
  actions: {
    text: string;
    link: string;
    theme: 'brand' | 'alt';
  }[];
}

For example, use the following frontmatter to specify a page's hero configuration:

---
pageType: home

hero:
  name: Rspress
  text: A Documentation Solution
  tagline: A modern documentation development technology stack
  actions:
    - theme: brand
      text: Introduction
      link: /en/guide/introduction
    - theme: alt
      text: Quick Start
      link: /en/guide/getting-started
---

When setting hero.text, you can use the | symbol in YAML to manually control line breaks:

---
pageType: home

hero:
  name: Rspress
  text: |
    A Documentation
    Solution

You can also use HTML in the page's hero configuration:

---
pageType: home

hero:
  name: <span class="hero-name">Rspress</span>
  text: <span class="hero-text">A Documentation Solution</span>
  tagline: <span class="hero-tagline">A modern documentation development technology stack</span>
  actions:
    - theme: brand
      text: <span class="hero-actions-text">Introduction</span>
      link: /en/guide/introduction
    - theme: alt
      text: <span class="hero-actions-text">Quick Start</span>
      link: /en/guide/getting-started
---

#features

• Type: Array
• Default: []

Feature configuration for the home page. It has the following type:

interface Feature {
  title: string;
  details: string;
  icon: string;
  // The length of the card grid, currently only supports [3, 4, 6]
  span?: number;
  // The link of the feature card, optional.
  link?: string;
}

export type Features = Feature[];

For example, use the following frontmatter to specify the features for the home page:

---
pageType: home

features:
  - title: 'MDX: Write content with flexible syntax'
    details: MDX is a powerful way to write content. You can use React components in Markdown.
    icon: 📦
  - title: 'Feature Rich: One-stop solution'
    details: Out-of-the-box support for full-text search, i18n, and other common features.
    icon: 🎨
  - title: 'Highly Extensible: Multiple customization paths'
    details: Use extension APIs to customize the theme UI and build behavior.
    icon: 🚀
---