#Front matter config

This document introduces how to configure various properties of a page using front matter, including title, description, page type, navbar, etc.

See Frontmatter for what front matter is and how to use it, and see useFrontmatter for how to access front matter in code.

#title

• Type: string

The title of the page. By default, the page's h1 heading will be used as the title of the HTML document. But if you want to use a different title, you can use front matter to specify the title of the page. For example:

---
title: My Home Page
---

This is my **home page content**.

It is equivalent to:

# My home page

This is my **home page content**.

#description

• Type: string

A custom description for the page, which generates a meta tag for SEO optimization. For example:

---
description: This is my home page
---

It will generate a <meta name="description" content="This is my home page" /> tag on the page.

#pageType

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

The type of the page. By default, the page type is doc. But if you want to use a different page type, you can use the front matter field pageType to specify the page type. E.g:

---
pageType: home
---

The meaning of each pageType config is as follows:

• home: Home page, including the layout content of the top navigation bar and home page.
• doc: Doc page, including top navigation bar, left sidebar, body content, and outline bar on the right.
• doc-wide: Wide doc page, when using the outline: false and sidebar: false settings together, the main content will automatically occupy a wider screen space.
• custom: Custom page, including top navigation bar and custom content.
• blank: Also belongs to custom page, but does not include Top Navigation Bar.
• 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 the suffix is -, you can also use | for separation:

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

#sidebar

Whether to show the sidebar on the left. By default, the doc page will display the sidebar on the left. If you want to hide the sidebar on the left, you can use the following front matter config:

---
sidebar: false
---

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

#outline

Whether to display the outline column on the right. By default, the doc page displays the outline column on the right. You can hide the outline column with the following config:

---
outline: false
---

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

#footer

Whether to display the components at the bottom of the document (such as previous/next page). By default, the doc page will display the footer at the bottom. You can hide the footer with the following config:

---
footer: false
---

#navbar

Whether to show the top navigation bar. By default, all pages will display the top navigation bar. But if you want to hide the top navigation bar, you can use the following front matter config:

---
navbar: false
---

#context

• Type: string

After configuration, the data-context attribute will be added to the DOM node when the sidebar is generated, and the value is the configured value.

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

#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

Enable the overview page feature in the document page. If set to true, it means the current page is an Overview Page. For example:

---
overview: true
---

#overviewHeaders

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

The header levels shown in the overview page. By default, the displayed header is h2. But if you want to display different header levels, you can specify it using the overviewHeaders front matter field. For example:

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

Or

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

#Home page related

The following configurations are related to the Home Page feature.

#hero

• Type: Object

The hero config for the home page. It has the following types:

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

For example, you can use the following front matter to specify a page's hero config:

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

Or you can use HTML to specify the hero config for the page:

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

The features config of the home page. It has the following types:

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, you could use the following to specify the features configuration 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: Provides multiple customization capabilities'
    details: Through its extension mechanism, you can easily extend the theme UI and build capabilities.
    icon: 🚀
---