约定式路由#

什么是约定式路由#

Rspress 使用的是文件系统路由，页面的文件路径会简单的映射为路由路径，这样会让整个项目的路由非常直观。

例如，如果在 docs 目录中有一个名为 foo.md 的文件，则该文件的路由路径将是 /foo。

映射规则#

Rspress 会自动扫描根目录和所有子目录，并将文件路径映射到路由路径。例如，如果你有以下的文件结构：

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

那么 bar.md 的路由路径会是 /foo/bar，foo.md 的路由路径会是 /foo。

具体映射规则如下：

组件路由#

在约定式路由中，除了 .md(x) 文件，还可以使用 .tsx 文件作为路由组件，在 .tsx 中默认导出一个组件，该组件会被自动注册到路由中。例如：

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

当然，如果你想要定制布局，可以添加一个导出，声明布局类型，例如：

export const frontmatter = {
  // 声明布局类型
  // 这里的 custom 布局中不会出现侧边栏
  pageType: 'custom',
};

各个 pageType 的含义详情请参考 API 文档。

自定义行为#

如果要自定义路由行为，可以使用配置文件中的 route 字段。例如：

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/**/*'],
  }
});

最佳实践#

我们推荐你将文档文件放在 docs 目录下，这样可以让你的项目更加清晰。而对于非文档内容，比如自定义组件、工具函数等，可以放到 docs 目录之外进行维护。比如：

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