控制导航生成

注意：导航仅在 site 模式下可用。

约定式导航规则

和菜单项及菜单分组一样，dumi 的导航也是建立在路由结构上生成的。路由的嵌套关系会被 dumi 解析为导航及导航下的菜单分组，还是看看 dumi 会怎么识别路由结构：

  1. /                       # 首页
  2. /guide                  # 指南导航 + 指南导航的首页
  3. /guide/help             # 指南导航 + 指南导航的帮助分组
  4. /other                  # 其他导航
  5. /very/very/deep/child   # very 导航 + very/deep 分组

然后这个识别结果会被展示为：

  1. # 导航头
  2. LOGO     Guide | Other | Very
  3. -----------------------------
  5. # 指南的侧边菜单
  6. -----
  7. Guide
  8. -----
  9. Help
  10. -----
  12. # 其他的侧边菜单
  13. -----
  14. Other
  15. -----
  17. # Very 的侧边菜单
  18. -----
  19. Very/deep
  20. -----
  21.   Child
  22. -----

总结一下约定式生成的逻辑：文件夹的第一级嵌套会作为导航，第二级至倒数第二级嵌套会作为侧边菜单，最后一级是页面；第一级嵌套下的所有菜单和页面会被归集到该导航下。

但仅依靠自动规则往往是不够的，我们通常还有定制导航头文字和顺序的需要：

控制导航名称

导航名称的默认生成规则是，取当前导航的路由名称去掉 / 并首字母大写。比如，路由是 /guide，dumi 将会取 guide 并首字母大写变成 Guide。

如果希望手动控制导航名称，可以使用 nav.title 的 frontmatter 配置项进行配置；注意，同一导航文件夹下只需要在任意 Markdown 文件中配置，则会全体生效。

控制导航路径

导航路径的默认生成规则是，取路由的第一级嵌套。比如，路由是 /very/very/deep/child，那么 very 则会作为导航路径。

如果希望手动控制导航路径，可以使用 nav.path 的 frontmatter 配置项进行配置。

不同于 nav.title，由于 nav.path 作为唯一标识符，手动控制的话即便同一文件夹下也需要每个 Markdown 文件都设置，所以通常还是建议用文件夹来组织导航而不是手动控制。

控制导航顺序

导航的默认排序规则为，先对比 path 的长度，例如 /guide 肯定排在 /guide/help 前面，其次对比导航名称的 ASCII 码，比如 Guide 肯定排在 Help 前面。

如果希望手动控制导航顺序，可以使用 nav.order 的 frontmatter 配置项进行配置，数字越小越靠前；和 nav.title 一样，同一导航文件夹下只需要在任意 Markdown 文件中配置，就会全体生效。

控制菜单生成

请参考 控制菜单生成，需要注意的是，在 site 模式下，由于导航作为第一级嵌套，菜单的自动解析都是从第二级嵌套开始的。

配置式导航

在大部分场景下，我们都需要对导航上展示的内容做定制，例如添加 GitHub 的仓库链接、旧版文档的链接等等，可以使用 navs 配置项 来实现：

  1. // config/config.ts 或 .umirc.ts
  2. export default {
  3.   // 单语言配置方式如下
  4.   navs: [
  5.     null, // null 值代表保留约定式生成的导航，只做增量配置
  6.     {
  7.       title: 'GitHub',
  8.       path: 'https://github.com/umijs/dumi',
  9.     },
  10.   ],
  12.   // 多语言配置方式如下
  13.   navs: {
  14.     // 多语言 key 值需与 locales 配置中的 key 一致
  15.     'en-US': [
  16.       null, // null 值代表保留约定式生成的导航，只做增量配置
  17.       {
  18.         title: 'GitHub',
  19.         path: 'https://github.com/umijs/dumi',
  20.       },
  21.     ],
  22.     'zh-CN': [
  23.       null, // null 值代表保留约定式生成的导航，只做增量配置
  24.       {
  25.         title: 'GitHub',
  26.         path: 'https://github.com/umijs/dumi',
  27.       },
  28.     ],
  29.   },
  30. };

但此配置项只用于自定义导航头的展示项，并不会影响路由的生成，如果希望自定义路由路径，请 参考上方 在 Markdown 文件中通过 frontmatter 配置项进行控制。