@modern-js/doc-tools-doc/docs/zh/guide/basic/conventional-route.mdx

Website for @modern-js/doc-tools

# 约定式路由

## 什么是约定式路由

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

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

## 映射规则

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

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

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

具体映射规则如下：

| 文件路径        | 路由路径   |
| --------------- | ---------- |
| `index.md`      | `/`        |
| `/foo.md`       | `/foo`     |
| `/foo/bar.md`   | `/foo/bar` |
| `/zoo/index.md` | `/zoo`     |

## 组件路由

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

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

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

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

各个 pageType 的含义详情请参考[API 文档](/api/config/config-frontmatter#pagetype)。

## 自定义行为

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

```ts title="modern.config.ts"
import { defineConfig } from '@modern-js/doc-tools';

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` 目录之外进行维护。比如：

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