Auto Nav/Sidebar#

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.

Basic Concept#

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:

docs
├── _meta.json // navigation bar level
└── guides
    ├── _meta.json // sidebar level
    ├── introduction.mdx
    └── advanced
        ├── _meta.json // sidebar level
        └── plugin-development.md

If your document supports i18n, then _meta.json at the navigation bar level will be placed in the corresponding language directory, for example:

docs
├── en
│   ├── _meta.json // navigation bar level
│   └── guides
│       ├── _meta.json // sidebar level
│       ├── introduction.mdx
│       ├── install.mdx
│       └── advanced
│           ├── _meta.json // sidebar level
│           └── plugin-development.md
└── zh
    ├── _meta.json // navigation bar level
    └── guides
        ├── _meta.json // sidebar level
        ├── introduction.mdx
        ├── install.mdx
        └── advanced
            ├── _meta.json // sidebar level
            └── plugin-development.md

Navbar Level Config#

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:

[
  {
    "text": "Guide",
    "link": "/guides/introduction",
    "activeMatch": "^/guides/"
  }
]

Sidebar Level Config#

In the case of the sidebar level, you can fill in _meta.json an array with each item of the following type:

export type SideMetaItem =
  | string
  | {
      type: 'file';
      name: string;
      label?: string;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
    }
  | {
      type: 'dir';
      name: string;
      label?: string;
      collapsible?: boolean;
      collapsed?: boolean;
      tag?: string;
      overviewHeaders?: number[];
      context?: string;
    }
  | {
      type: 'divider';
      dashed?: boolean;
    };

string#

When the type is string, it means that the item is a file, and the file name is the string, for example:

["introduction"]

The file name may or may not have a suffix, for example introduction will be parsed as introduction.mdx.

object#

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:

{
  type: 'file';
  name: string;
  label?: string;
  overviewHeaders?: number[];
  context?: string;
}

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]. context means adding the value of the data-context attribute to the DOM node when generating the sidebar, it is an optional value and will not be added by default. For example:

{
  "type": "file",
  "name": "introduction",
  "label": "Introduction"
}

In the case of describing directories, the types are as follows:

{
  type: 'dir';
  name: string;
  label?: string;
  collapsible?: boolean;
  collapsed?: boolean;
  overviewHeaders?: number[];
  context?: string;
}

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]. context means adding the value of the data-context attribute to the DOM node when generating the sidebar, it is an optional value and will not be added by default. For example:

{
  "type": "dir",
  "name": "advanced",
  "label": "Advanced",
  "collapsible": true,
  "collapsed": false
}

In the case of describing divider, the types are as follows:

{
  type: 'divider';
  dashed?: boolean;
}

When dashed is set to true, it indicates that the divider line is dashed. Otherwise, it is solid.

docs
├── advanced.mdx
└── advanced
  ├── _meta.json
  └── ...

In the case of describing section header, the type is as follows:

{
  type: 'section-header';
  label: string;
}

Here, label represents the display name of this section header in the sidebar, for example:

{
  "type": "section-header",
  "label": "Section Header"
}

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:

[
  {
    "type": "section-header",
    "label": "Section 1"
  },
  "introduction",
  {
    "type": "divider"
  },
  {
    "type": "section-header",
    "label": "Section 2"
  },
  "advanced"
]

In the case of describing custom link, the types are as follows:

{
  type: 'custom-link';
  link: string;
  label: string;
}

Among them, link indicates the link address, label indicates the display name of the link in the sidebar, for example:

{
  "type": "custom-link",
  "link": "/my-link",
  "label": "My Link"
}

link support external links, for example:

{
  "type": "custom-link",
  "link": "https://github.com",
  "label": "GitHub"
}

Complete Example#

Here is a complete example using the three types above:

[
  "install",
  {
    "type": "file",
    "name": "introduction",
    "label": "Introduction"
  },
  {
    "type": "dir",
    "name": "advanced",
    "label": "Advanced",
    "collapsible": true,
    "collapsed": false
  },
  {
    "type": "custom-link",
    "link": "/my-link",
    "label": "My Link"
  }
]

No Config Usage#

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:

docs
├── _meta.json
└── guides
  ├── _meta.json
  └── basic
    ├── introduction.mdx
    ├── install.mdx
    └── plugin-development.md

In the guides directory you can configure _meta.json as follows:

[
  {
    "type": "dir",
    "name": "basic",
    "label": "Basic",
    "collapsible": true,
    "collapsed": false
  }
]

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:

basic
  ├── 1-introduction.mdx
  ├── 2-install.mdx
  └── 3-plugin-development.md

Add SVG Icons Before Titles#

In addition, you can add icons before the title through the tag confing, like this:

{
  "type": "file",
  "name": "introduction",
  "label": "Introduction",
  "tag": "<svg width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M4 6h24v2H4zm0 18h24v2H4zm0-12h24v2H4zm0 6h24v2H4z\"/></svg>"
}

The value of tag is a svg tag string or image url, which you can configure in the navbar or sidebar.