[RFC] conventional 2-level navigations

[PeachScript]

需求描述

dumi 2 目前不支持二级导航，但在实际的文档组织过程中三级目录是常见场景，比如我们希望对 pc 和 mobile 两种平台提供不同的文档描述：

docs
└── platforms
    ├── pc
    │   ├── index.md
    │   └── faq.md
    └── mobile
        ├── index.md
        └── faq.md

当前上述结构会生成 Platfroms、PC 和 Mobile 三个一级导航，并且 platforms/pc 和 platforms/mobile 会归属在 Platforms 下，倘若能将 PC 和 Mobile 两者收在 Platforms 一级导航内，显然是更加干净和符合期望的方案。

需求边界

是否要支持三级导航？

不支持。如果文档目录结构的复杂度超过 3 级，应该考虑优化文档整体结构而非使用三级导航。

是否支持 dumi 1 的『隔空关联』？

不支持。dumi 1 的『隔空关联』是指两个本不在同一父级目录下的文档，通过 nav.path 强制指定到同一目录下，但这会加重文档的维护负担，框架实现也更复杂，所以 dumi 2 仅会支持同一父级目录下的约定式二级导航；不过由于原子资产目录本身不支持嵌套，所以会支持配置式的关联，参考下方『是否支持把不同的 atomDirs 解析为一组二级导航？』部分。

是否支持把二级导航的文档合并到一级里展示？

不支持。约定式导航的目的是希望与文档目录结构尽量保持一致，如果要合并应该在文件目录结构里将嵌套的文档提到父级，可以用统一前缀来区分，类似：

# 合并 PC 和 Mobile 二级导航的文档到一级里
docs
└── platforms
    ├── pc-faq.md
    └── mobile-faq.md

是否支持把不同的 atomDirs 解析为一组二级导航？

支持。需确保 type 一致、且拥有不同的 subType，具体参考下方『原子资产组织方式』。

方案用法

文档组织方式

目录结构即上方『背景描述』所述。最终将会生成如下路由：

/platforms/pc
/platforms/pc/faq
/platforms/mobile
/platforms/mobile/faq

原子资产组织方式

目录结构还是保持原子资产的原有结构，在 .dumirc.ts 中配置路由生成规则，加上统一的前缀路由和不同的类型子路径，例如：

// .dumirc.ts
export default  {
  resolve: {
    atomDirs: [
      { type: 'component', subType: 'pc', dir: 'packages/pc-components/src' },
      { type: 'component', subType: 'mobile', dir: 'packages/mobile-components/src' },
    ]
  }
}

其中 subType 为本次新增配置项，最终将会生成如下路由，整体逻辑相当于用 type 和 subType 模拟了 3 级目录结构：

/components/pc/foo
/components/pc/bar
/components/mobile/foo
/components/mobile/bar

配置一级导航

新增 nav.second FrontMatter，和 nav 一样，相同二级导航的页面只需配置其中一个 md 即可全部生效，示例：

---
nav:
  second: 支持平台
# or
nav:
  second:
    title: 支持平台
    order: 1
---

方案实现

主要有 4 个改造点，theme-api 的 useFullSidebarData & useNavData hook、路由生成插件 features/routes 和默认主题的 slots/Navbar，分别对应数据生成和 UI 渲染。

useFullSidebarData

目前侧边栏数据是按照父级目录归类的，比如 /a/b 会被归类到 /a 的导航下，但 /a/b 的源文件可以是 a/b/index.md 也可以是 a/b.md，两者在约定式二级导航中的语义是完全不同的；所以为了支持约定式二级导航，生成侧边栏数据时就必须对文件目录结构做感知。

通过判断 route.meta.frontmatter.filename，如果是 index.md 结尾则自动将父级目录变深一层，比如：

1. a/b/index.md 的父级目录为 /a/b 而非此前的 /a
2. a/b.md 的父级目录仍为 /a
3. a.md 与 a/index.md 由于层级不足，所以父级目录仍为 /a

这样一来 useFullSidebarData 返回的侧边栏路径就与文件目录结构完全相符了；需要注意的是，这个改动也许会带来 Breaking Change，但考虑到 a/b 文件夹下只放一个 index.md 的用法应当比较少见，所以先不考虑向前兼容的逻辑。

useNavData

仍然基于 useFullSidebarData 的数据做导航生成，但需要多做一些中间处理，整体流程如下（仅关注新增部分即可）：

1. 遍历 sidebar 数据，生成导航数据（含排序字段）
2. [新增] 对导航数据做二次加工：
   a. 把 2 级以上路径的导航数据归类到同一个一级导航下（至少存在 2 个二级导航才做归类）
   b. 根据 nav.second 填充一级导航数据（含排序字段）
3. [新增]对一级及二级导航做排序
4. 拼接用户的导航数据
5. 返回 NavData

对 2 处理的部分做示例：

// 处理前
[
  { link: '/a/b1/x', ... },
  { link: '/a/b2/x', ... },
  { link: '/c/d1/x', ... },
  { link: '/c/d2/x', ... },
  { link: '/c/d3', ... },
  { link: '/e/f/g', ... },
]
// 处理后
[
  { children: [{ link: '/a/b1/x' }, { link: '/a/b2/x' }], ... },
  { link: '/c/d3', children: [{ link: '/a/b1/x' }, { link: '/a/b2/x' }], ... },
  { link: '/e/f/g', ... },
]

规则归纳：

1. 在相同一级路径下，必须存在 2 个及以上的三级路径才能形成二级导航
2. 在相同一级路径下，如果仅存在三级路径，则只展示下拉菜单，一级导航本身不带超链
3. 在相同一级路径下，在 2 的基础上还存在二级或一级路径，则一级导航除了下拉菜单外也带超链，超链值与当前逻辑一致

改造该 hook 的同时，还需要关注配置式的二级导航是否能正常工作。

features/routes

主要是识别 subType 并拼接到对应的位置上，改动比较简单，关键代码位置：

dumi/src/features/routes.ts

Line 251 in a244fba

const routeFile = winPath(path.join(plural(type), file));

slots/Navbar

UI 渲染的关键点在交互上，先大致画了下 UI：

其中 PC 的交互说明：

1. 鼠标 hover 出现下拉
2. 二级导航项的高亮色为主色，命中色为加粗加深（与一级导航一致）
3. 二级导航的最小宽度为一级导航宽度 + 左右各外扩 12px
4. 二级导航的最大宽度暂不做限制，统一向右扩展

H5 的交互说明：

1. 点击箭头可切换二级导航的展示，如果该一级导航不带超链，则点击本体也可切换二级导航的展示
2. 二级导航项的命中色为加粗加深（与一级导航一致）
3. 二级导航项有命中时，默认展开

向前兼容

考虑到 dumi 已经有数个三方主题包，以及可能有不少用户在使用自定义本地主题特性，约定式二级导航的发布会导致 useNavData、useSidebarData 及 useFullSidebarData 这 3 个 hook 的返回值发生变化，也就可能导致主题渲染崩溃或不符合预期。

所以 dumi 2.2 需要考虑向前兼容方案，打算基于版本号声明来判断是否启用二级导航：

1. 项目使用三方主题包：dumi 会基于主题包 peerDependencies 中 dumi 的版本号来判断是否要启用配置项
2. 项目自定义本地主题：dumi 会基于项目 devDependencies 中 dumi 的版本号来判断是否要启用配置项
3. 项目使用默认主题：同 2

还有 3 个子任务需要完成：

1. 更新脚手架的 dumi 版本号为 ^2.2.0，确保新建的主题包和文档应用都默认使用约定式二级导航
2. 更新主题包插件，确保旧的主题包在研发时可以收到 dumi 约定式导航的支持提示
3. 更新官方移动端主题的版本声明

参与共建

方案讨论确定后，感兴趣的小伙伴可以领任务参与共建，应该分两个任务即可：

1. 数据层任务，改造 routes 插件、useFullSidebarData、useNavData hook
2. UI 层任务，改造 slots/Navbar

[PeachScript]

PR: #1665