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

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

The specific mapping rules are as follows:

#TSX 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/core';

export default defineConfig({
  route: {
    // These files will be registered as routes (supports glob pattern)
    include: ['other-dir/**/*'],
    // These files will not be registered as routes (supports glob pattern)
    exclude: ['components/**/*', 'fragments/**/*'],
  },
});

#Exclude files starting with _ by default

In the docs directory, MDX fragments or React components need to be excluded from routing through the route.exclude configuration. For convenience, files starting with "_" are excluded by default via route.excludeConvention.

You can also place components in adjacent directories outside the docs directory, for example:

import ButtonFragment from './_button.mdx';
import Button from '../../components/button';

<ButtonFragment />
<Button />

#### button

This is text from MDX

const Button = () => <button>This is a button from tsx</button>;
export default Button;

It will be rendered as:

#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. If placed in the docs directory, you need to use route.exclude together.

Here is a best practice file structure that includes MDX fragments and React components, custom themes, conventional routing, and internationalization:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    exclude: ['*/components/**/*', '*/fragments/**/*'], // Files in these directories won't be registered as routes
  },
  lang: 'en',
  locales: [
    {
      lang: 'zh',
      label: '中文',
    },
    {
      lang: 'en',
      label: 'English',
    },
  ],
});

{
  "compilerOptions": {
    "lib": ["DOM", "ESNext"],
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "paths": {
      "i18n": ["./i18n.json"],
      "@theme": ["./theme/index.tsx"]
    }
  },
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}