close
Rspress
Guide
Plugin
API
Guide
Plugin
API

Overview Page

Effect

Rspress has a built-in preview page, the effect is as follows:

How to use

Generating the preview page requires the following two steps:

1. Create a new directory and configure frontmatter

For example, create the following directories and files

├── docs
│   ├── index.md
│   ├── api
│   │   ├── index.md
│   │   ├── theme
│   │   │  ├── component.mdx
│   │   │  ├── utils.mdx
// ...

We add the following to api/index.md:

---
overview: true
---
NOTE

The title of the overview page can be configured through frontmatter. The default value is Overview. After title is configured in frontmatter, there is no need to write an H1 title in the markdown content.

---
overview: true
title: Overview
---

This is an Overview page of our website.

2. Configuring _meta.json

The content structure of the overview page will be automatically generated according to _meta.json and the corresponding h1, h2 titles of the article. For example, the configuration of api/_meta.json is as follows:

[
  {
    "type": "file",
    "name": "index",
    "label": "API Overview"
  },
  {
    "type": "dir",
    "name": "theme",
    "label": "Theme"
  }
]

At the same time, the file api/theme/_meta.json has the following content:

["component", "utils"]

The detailed configuration usage of _meta.json can be referred to Auto Nav/Sidebar.

In the above configuration, the final preview page will generate a group called Theme, which contains the h1, h2 titles of two articles: component.md(x) and utils.md(x). Of course, you can also refer to the config of the Theme group to add more groups.

If you want to control the headers displayed in the overview page, you can configure it through overviewHeaders config in _meta.json, which defaults to [2] and you can also configure FrontMatter with overviewHeaders: [2] in exact file.

If you want to generate a sub-preview page under theme, there are two ways:

  1. Create a new file theme.md with the same name in the parent directory of theme and configure the frontmatter of overview: true.
├── docs
│ ├── index.md
│ ├── api
│ │ ├── index.md
│ │ ├── theme.md
│ │ ├── theme
│ │ │ ├── component.mdx
│ │ │ ├── utils.mdx
//...
  1. Create a new index.md in the theme directory and configure the frontmatter of overview: true.
├── docs
│ ├── index.md
│ ├── api
│ │ ├── index.md
│ │ ├── theme
│ │ │ ├── index.md
│ │ │ ├── component.mdx
│ │ │ ├── utils.mdx
//...

Then configure theme/_meta.json as follows:

[
  {
    "type": "file",
    "name": "index",
    "label": "Overview"
  }
]