In Rspress, in addition to declaring nav and sidebar through themeConfig
in the config file, you can also automatically generate the nav bar and sidebar by declaring the _meta.json
description file. We recommend the latter because it can make the config file more concise and clear.
Automated navbar/sidebar will only work if there are no nav
and sidebar
configurations in the config file rspress.config.ts
.
First, _meta.json
can be divided into two categories: navbar level and sidebar level. The difference between the two is that the navigation-level _meta.json
lives in the document root, while the sidebar-level _meta.json
lives in a subdirectory of the document root. for example:
If your document supports i18n, then _meta.json
at the navigation bar level will be placed in the corresponding language directory, for example:
In the case of the navigation bar level, you can fill in an array in _meta.json
, and its type is exactly the same as the nav config of the default theme. For details, please refer to nav config. for example:
In the case of the sidebar level, you can fill in _meta.json
an array with each item of the following type:
When the type is string
, it means that the item is a file, and the file name is the string, for example:
The file name may or may not have a suffix, for example introduction
will be parsed as introduction.mdx
.
When the type is an object, you can describe it as a file, a directory or a custom link.
In the case of describing file, the types are as follows:
Among them, name
means the file name, with
/without
suffix is supported, label
means the display name of the file in the sidebar.label
is an optional value, if it is not filled, it will automatically take the h1 title in the document. overviewHeaders
means the headers displayed in the overview page of the file. It is an optional value and the default value is [2]
. For example:
In the case of describing directories, the types are as follows:
Among them, name
indicates the directory name, label
indicates the display name of the directory in the sidebar, collapsible
indicates whether the directory can be collapsed, collapsed
indicates whether the directory is collapsed by default, and overviewHeaders
indicates the headers displayed on the overview page for files in this directory. It is an optional value and the default value is [2]
. For example:
In the case of describing divider, the types are as follows:
When dashed
is set to true
, it indicates that the divider line is dashed. Otherwise, it is solid.
If you want to display a document when clicking on the sidebar directory, you can create an md(x)
file with the same name at the same level as the current directory, for example:
In this way, when you click on the Advanced
directory, the content of the advanced.mdx
file will be displayed.
In the case of describing section header, the type is as follows:
Here, label
represents the display name of this section header in the sidebar, for example:
This way, you can add section headers to the sidebar, which makes it easier to group documents and directories. Generally, you can use it in conjunction with divider
to better distinguish different groups. For example:
In the case of describing custom link, the types are as follows:
Among them, link
indicates the link address, label
indicates the display name of the link in the sidebar, for example:
link
support external links, for example:
Here is a complete example using the three types above:
In some directories, you don't need to configure _meta.json
and let the framework automatically generate the sidebar. This requires ensuring that the directory contains only documents, not subdirectories, and you have no requirements for the order of documents. For example, there is now the following document structure:
In the guides directory you can configure _meta.json
as follows:
In basic
directory, you may not configure _meta.json
, and then the framework will automatically generate a sidebar for you, the default is sorted alphabetically according to the file name. If you want to customize the order, you can prefix the file name with a number, such as:
In addition, you can add icons before the title through the tag
confing, like this:
The value of tag
is a svg tag string or image url, which you can configure in the navbar or sidebar.