docs: improve conventional-routing guide

Author: PeachScript

docs/guide/conventional-routing.md

@@ -6,43 +6,84 @@ order: 3
 
 # 约定式路由
 
-为了使得路由生成更容易理解、更易于控制，dumi 对 Markdown 文档的目录解析做了『文档路由』及『资产路由』的概念拆分。
+即根据路由文件路径自动生成路由，是 dumi 默认且推荐使用的路由模式。在 dumi 里，约定式路由一共有 3 种读取方式，分别是：
 
-默认情况下，`docs` 目录下的 Markdown 文档及`.dumi/pages` 下的 React 组件会根据目录结构解析为文档路由，`src` 目录下第一层级的 Markdown 文档会被解析为 `/components` 下的资产路由，我们可以通过配置项 `resolve.atomDirs` 对资产路由前缀及解析目录进行更改。
+| 类型                                                 | 默认读取路径                                            | 适用场景及特点                                                                                                                                        |
+| ---------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 文档路由                                             | `docs`                                                  | 适用于普通文档生成路由，路径下的文档会根据嵌套结构自动识别并归类到不同的导航类目下                                                                    |
+| 资产路由                                             | `src`                                                   | 适用于资产（比如组件或 hooks）文档的生成，路径下**第一层级**的文档会被识别并归类到指定的类别下，dumi 默认会将 `src` 下的文档都归类到 `/components` 下 |
+| <span style="white-space: nowrap;">React 路由</span> | <span style="white-space: nowrap;">`.dumi/pages`</span> | 适用于为当前站点添加额外的、无法用 Markdown 编写的复杂页面，这些页面必须使用 React 编写，识别规则与文档路由一致                                       |
 
-举几个例子方便理解：
+## 路由识别及转换
 
-| 磁盘路径                            | 解析结果                                            |
-| ----------------------------------- | --------------------------------------------------- |
-| /path/to/.dumi/pages/hello.tsx      | - 导航：Hello<br>- 页面路由：/hello                 |
-| /path/to/docs/hello.md              | - 导航：Hello<br>- 页面路由：/hello                 |
-| /path/to/docs/hello/index.md        | - 导航：Hello<br>- 页面路由：/hello                 |
-| /path/to/docs/hello/world/dumi.md   | - 导航：Hello<br>- 页面路由：/hello/world/dumi      |
-| /path/to/src/hello.md               | - 导航：Components<br>- 页面路由：/components/hello |
-| /path/to/src/hello/index.md         | - 导航：Components<br>- 页面路由：/components/hello |
-| /path/to/src/hello/world.md         | 不识别                                              |
-| /path/to/src/hello/another/world.md | 不识别                                              |
+dumi 的路由识别规则如下：
 
-除此之外，以下内容也不会被识别：
+- 在识别文档路由时，dumi 会自动过滤掉以 `.` 和 `_` 开头的文件及文件夹，仅识别 `.md` 后缀的文件，识别路径可通过 [`resolve.docDirs`](../config/index.md#resolve) 进行修改；
+- 在识别资产路由时，dumi 仅识别第一层级的 `.md` 文件及第二层级的 `index.md`、`README.md` 文件，并自动为路由路径加上资产类别前缀（`type` 配置项），识别路径及资产类别前缀可通过 [`resolve.atomDirs`](../config/index.md#resolve) 进行修改；
+- 在识别 React 路由时，dumi 会自动过滤掉以 `.` 和 `_` 开头的文件及文件夹，仅识别 `.tsx`、`.ts`、`.jsx` 和 `.js` 后缀的文件，过滤规则可通过 [`conventionRoutes.exclude`](../config/index.md#conventionroutes) 进行修改。
 
-1. 以 `.` 开头的目录及文档
-2. 以 `_` 开头的目录及文档
+除此之外，为了使得 URL 更加友好，dumi 会自动将文件路径中的驼峰命令（CamelCase）转换为中划线命名（kebab-case），例如 `docs/HelloWorld.md` 最终会生成 `/hello-world`。
 
-### 自定义导航、分组和标题
+## 文档标题及排序
 
-如果希望控制导航/分组/页面标题的生成，可以通过**在 Markdown 文件顶部**编写 FrontMatter 实现：
+dumi 会自动将 Markdown 文件中的第一个标题作为该文档的标题，如果没有标题，则会使用文件名作为标题，以及在同一导航类目、同一菜单分组下的文档，默认按照字典序排序。
+
+这两者都可以在该文档的 Markdown 源文件头部通过 FrontMatter 手动指定，比如：
+
+```md
+title: 文档标题
+order: 1 <!-- order 越小越靠前，默认为 0 -->
+```
+
+## 导航归类及生成
+
+dumi 始终以路由路径作为导航归类的依据，拥有相同父级路径的文档会被归类到同一个导航类目下，例如 `/config` 和 `/config/advanced` 会被归类到 `Config` 导航类目下。
+
+导航的名称默认为该导航类目下第一篇文档的分组标题或文档标题，导航的排序默认按照字典序排序，这两者都可以在该导航类目下**任一文档**的 Markdown 源文件头部通过 FrontMatter 指定，比如：
 
 ```md
 ---
-title: 自定义页面名称
-order: 控制页面顺序，数字越小越靠前，默认以路径长度和字典序排序
+# 单独设置导航名称
+nav: 配置项
+# 同时设置导航名称和顺序，order 越小越靠前，默认为 0
 nav:
-  title: 自定义导航名称
-  order: 控制导航顺序，数字越小越靠前，默认以路径长度和字典序排序
-group:
-  title: 自定义分组名称
-  order: 控制分组顺序，数字越小越靠前，默认以路径长度和字典序排序
+  title: 配置项
+  order: 1
 ---
+```
+
+需要注意的是，目前 dumi 尚不支持二级导航，所以如果路由路径存在超过 2 层嵌套，则会会从第 2 层开始形成新的一级导航，这并非推荐的用法，请耐心等待 dumi 对二级导航的原生支持。
+
+## 菜单归类及生成
 
-<!-- 其他 Markdown 内容 -->
+dumi 默认会将同一导航类目下的所有文档都归类到默认菜单分组下，默认菜单分组没有分组名称，且默认排序会先于其他分组。
+
+倘若你的文档比较多，希望像这篇文档左边的菜单一样，将相关联的文档归类到同一菜单分组下，可以在相关文档的 Markdown 源文件头部通过 FrontMatter 指定它的分组及分组顺序，比如：
+
+```md
+---
+# 单独设置分组名称
+group: 基础
+# 同时设置分组名称和顺序，order 越小越靠前，默认为 0
+group:
+  title: 基础
+  order: 1
+---
 ```
+
+与导航不同的是，需要归类的每一篇文档都需要设置菜单分组名称，但菜单分组顺序仅需要**任一文档**设置即可生效。
+
+## 解析示例
+
+| 磁盘路径                   | 路由类别   | 解析结果                                                  |
+| -------------------------- | ---------- | --------------------------------------------------------- |
+| docs/hello.md              | 文档路由   | - 导航：Hello<br>- 页面路由：/hello                       |
+| docs/hello/index.md        | 文档路由   | - 导航：Hello<br>- 页面路由：/hello                       |
+| docs/hello/world/dumi.md   | 文档路由   | - 导航：Hello<br>- 页面路由：/hello/world/dumi            |
+| src/HelloWorld.md          | 资产路由   | - 导航：Components<br>- 页面路由：/components/hello-world |
+| src/HelloWorld/index.md    | 资产路由   | - 导航：Components<br>- 页面路由：/components/hello-world |
+| .dumi/pages/hello.tsx      | React 路由 | - 导航：Hello<br>- 页面路由：/hello                       |
+| docs/\_hello.md            | --         | 不识别，原因：以 `_` 开头                                 |
+| src/hello/world.md         | --         | 不识别，原因：资产路由只识别第一层级                      |
+| src/hello/another/index.md | --         | 不识别，原因：资产路由只识别第一层级                      |
+| .dumi/pages/hello.md       | --         | 不识别，原因：React 路由不识别 `.md` 后缀                 |