🚧 Rspress 2.0 document is under development
close
Rspress
  • English

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

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

      description

      • Type: string

      A custom description for the page. For example:

      ---
description: This is my custom description for this page.
---

      pageType

      • Type: 'home' | 'doc' | '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.
      • 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'
---
      • Type: [string, Record<string, string>][]

      Specify extra head tags to be injected for the current page. Will be appended after head tags injected by site-level config.

      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>

      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: /zh/guide/introduction
    - theme: alt
      text: <span class="hero-actions-text">Quick Start</span>
      link: /zh/guide/getting-started
---

      features

      • Type: Array
      • Default: []

      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 support[3, 4, 6]
  span?: number;
  // The link of the feature, not required.
  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 Support'
    details: MDX is a powerful way to write content. You can use React components in Markdown.
    icon: 📦
  - title: 'Feature Rich'
    details: Out of box support for i18n, full-text search etc.
    icon: 🎨
  - title: 'Customizable'
    details: You can customize the theme ui and the build process.
    icon: 🚀
---

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

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

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

      Whether to hide the top navigation bar. You can hide the top nav bar with the following config:

      ---
navbar: false
---

      overviewHeaders

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

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

      ---
overviewHeaders: []
---

      Or

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

      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.

      foo.mdx
      ---
context: 'context-foo'
---
      bar.mdx
      ---
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>