close
Rspress
  • 中文

      • 约定式路由

      什么是约定式路由

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

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

      映射规则

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

      docs
      foo
      bar.md
      index.md
      zoo.md
      index.md

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

      具体映射规则如下：

      文件路径路由路径cleanUrl: false 路径
      index.md//index.html
      /zoo.md/zoo/zoo.html
      /foo/index.md/foo//foo/index.html
      /foo/bar.md/foo/bar/foo/bar.html
      Warning

      不要出现文件与文件夹同名的情况，会造成路由冲突，例如下面的文件结构是不允许的：

      docs
      foo
      index.md
      foo.md

      TSX 路由

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

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

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

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

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

      自定义行为

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

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    // 这些文件会被注册为路由（支持 glob 模式）
    include: ['other-dir/**/*'],
    // 这些文件将不会被注册为路由（支持 glob 模式）
    exclude: ['components/**/*', 'fragments/**/*'],
  },
});

      默认排除 _ 开头的文件

      在 docs 目录 中，使用 MDX 片段或 React 组件要通过 route.exclude 配置从路由中排除。为方便使用，我们约定以 "_" 开头的文件会被 route.excludeConvention 默认排除。

      你也可以将组件放到 docs 目录以外的相邻目录，例如：

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

<ButtonFragment />
<Button />

      它将被渲染为：

      button

      这是一段来自 MDX 的文本

      最佳实践

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

      Tip

      如果要将自定义组件、文档片段放在 docs 目录，需要配合 route.excludes 使用，否则这些文件会被自动注册为路由，可能会导致一些意外的问题。

      以下是一种文件结构的最佳实践，包含了 MDX 片段、自定义主题、约定式路由、国际化：

      docs
      components# 用于放置文档中使用到的 React 组件
      Example.tsx
      zh
      fragments# 用于放置一些 zh 的文档片段
      example.mdx
      index.mdx
      en
      fragments# 用于放置一些 en 的文档片段
      example.mdx
      index.mdx
      theme
      components# 用于放置主题相关的 React 组件
      DocFooter.tsx
      index.tsx
      rspress.config.ts
      import { defineConfig } from '@rspress/core';

export default defineConfig({
  route: {
    exclude: ['*/components/**/*', '*/fragments/**/*'], // 这些目录下的文件不会被注册为路由
  },
  lang: 'en',
  locales: [
    {
      lang: 'zh',
      label: '中文',
    },
    {
      lang: 'en',
      label: 'English',
    },
  ],
});
      tsconfig.json
      {
  "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
  }
}