#Conventional route

#What is it?

Rspress uses file system routing: each page file path maps directly to a route path, making project routes easy to understand.

For example, a file named foo.md in the docs directory is routed to /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 is routed to /foo/bar, and /foo/index.md is routed to /foo/.

The specific mapping rules are as follows:

#TSX routing

In conventional routing, .tsx files can also act as route components in addition to .md(x) files. By default, the component exported from a .tsx file is automatically registered as a route. For example:

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

To customize the layout, export frontmatter and declare the layout type:

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

For the meaning of each pageType, see 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 must be excluded from routing with route.exclude. For convenience, files starting with "_" are excluded by default through 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 is rendered as:

#Best practices

We recommend placing documentation files in the docs directory to keep the project structure clear. Keep non-documentation content, such as custom components and utility functions, outside docs when possible. If they must live in docs, exclude them with route.exclude.

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
  }
}