Conventional Route#

What is it?#

Rspress uses file system routing, and the file path of the page is simply mapped to the routing path, which makes the routing of the entire project very intuitive.

For example, if there is a file named foo.md in the docs directory, the routing path for that file will be /foo.

Mapping Rules#

Rspress automatically scans the root directory and all subdirectories, and maps file paths to route paths. For example, if you have the following file structure:

docs
├── foo
│   └── bar.md
└── foo.md

Then bar.md will be routed to /foo/bar, and foo.md will be routed to /foo.

The specific mapping rules are as follows:

Component Routing#

In conventional routing, in addition to .md(x) files, you can also use .tsx files as route components. By default, a component is exported in .tsx, and this component will be automatically registered in the route. For example:

export default () => {
  return <div>foo</div>;
};

Of course, if you want to customize the layout, you can add an export to declare the layout type. For example:

export const frontmatter = {
  // Declare layout type
  // The custom layout here will not have a sidebar
  pageType: 'custom',
};

For detailed meanings of each pageType, please refer to the API documentation.

Custom Behavior#

If you want to customize the routing behavior, you can use the route field in the configuration file. For example:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    // These files will be excluded from the routing (support glob pattern)
    exclude: ['component/**/*']
    // These files will be included in the routing (support glob pattern)
    include: ['other-dir/**/*'],
  }
});

Best Practices#

We recommend that you place documentation files in the docs directory to make your project more clear. For non-documentation content, such as custom components, util functions, etc., they can be maintained outside the docs directory. For example:

docs
└── foo.mdx
src
├── components
│   └── CustomComponent.tsx
└── utils
    └── utils.ts