feat: support conventional 2-level navigation (#1665)

* feat: implement conventional 2-level navigation

* feat: support to configure subType for atomDirs

* refactor: remove useless entityDirs schema

* docs: describe 2-level navigation usage

* docs: describe 2-level navigation frontmatter

* refactor: improve styles for nav dropdown

* docs: add faq for more than 2-level nav

* refactor: improve transition for nav dropdown triangle

* docs: add version badge for 2-level nav

Author: PeachScript

docs/config/index.md

@@ -31,10 +31,12 @@ export default defineConfig({
 
 #### atomDirs
 
-- 类型：`{ type: string; dir: string }[]`
+- 类型：`{ type: string; subType?: string; dir: string }[]`
 - 默认值：`[{ type: 'component', dir: 'src' }]`
 
-配置原子资产（例如组件、函数、工具等）Markdown 的解析目录，该目录下 **第一层级** 的 Markdown 文档会被解析为该实体分类下的路由，嵌套层级将不会识别。比如在默认配置下，`src/Foo/index.md` 将被解析为 `components/foo` 的路由。
+配置原子资产（例如组件、函数、工具等）Markdown 的解析目录。
+
+其中 `type` 用于指定资产类别，必须是 URL 友好的**单数单词**，比如 `component` 或者 `hook`；`subType` 用于指定资产的子类别，通常在需要生成二级导航时使用，值必须为 URL 友好的单词；`dir` 指定目录下**第一层级**的 Markdown 文档会被解析为该实体分类下的路由，嵌套层级将不会识别。比如在默认配置下，`src/Foo/index.md` 将被解析为 `components/foo` 的路由，`type` 配置值将**自动被复数化**后作为路由的前缀路径。
 
 单独将资产的解析逻辑拆分是为了解决 dumi 1 中普通文档与源码目录下的组件文档混淆不清、分组困难的问题。
 

docs/config/markdown.md

@@ -82,6 +82,32 @@ title: 配置页面标题
 
 配置页面简介，该值会用于生成 `<meta>` 标签。
 
+## nav
+
+- 类型：`string | { title: string; order: number; parent: { title: string; order: string } }`
+- 默认值：`undefined`
+
+配置当前页所属的一级导航及二级导航，同一导航类目下仅需配置任意一个 Markdown 文件即可全局生效，未配置时将会使用[默认规则](../guide/conventional-routing.md#导航归类及生成)。
+
+例如：
+
+```md
+---
+# 单独配置名称
+nav: 名称
+# 同时配置名称和顺序，order 越小越靠前，默认为 0
+nav:
+  title: 名称
+  order: 1
+  # 单独配置二级导航名称
+  parent: 父级名称
+  # 同时配置二级导航名称和顺序，order 越小越靠前，默认为 0
+  parent:
+    title: 父级名称
+    order: 1
+---
+```
+
 ## group
 
 - 类型：`string | { title: string; order: number }`

docs/guide/conventional-routing.md

@@ -52,7 +52,46 @@ nav:
 ---
 ```
 
-需要注意的是，目前 dumi 尚不支持二级导航，所以如果路由路径存在超过 2 层嵌套，则会会从第 2 层开始形成新的一级导航，这并非推荐的用法，请耐心等待 dumi 对二级导航的原生支持。
+### 约定式二级导航 <Badge>2.2.0+</Badge>
+
+同时，为了便于组织文档，dumi 还支持生成二级导航，使用起来也非常简单，以如下目录结构为例：
+
+```bash
+docs
+└── platforms
+    ├── pc
+    │   ├── index.md
+    │   └── faq.md
+    └── mobile
+        ├── index.md
+        └── faq.md
+```
+
+根据一级导航的规则，上面所有的 Markdown 必然都归属于 `Platforms` 导航，但同时它们还会分别归属于 `Pc` 和 `Mobile` 这两个二级导航，这是因为这些路由路径除了拥有共同的 `/platforms` 前缀外，还拥有各自的二级路径前缀，即 `/pc` 和 `/mobile`，二级导航的 UI 效果如下：
+
+<img src="https://gw.alipayobjects.com/zos/bmw-prod/85a246ef-5f74-4f70-97fe-f6b40968e0bf/lhpzbiod_w288_h232.jpeg" width="140" />
+
+二级导航的名称及顺序的默认规则与一级导航一致，类似的，我们也可以在该二级导航类目下**任一文档**的 Markdown 源文件头部通过 FrontMatter 指定，比如：
+
+```md
+---
+nav:
+  # 单独设置二级导航名称
+  parent: 移动端
+  # 同时设置二级导航名称和顺序，order 越小越靠前，默认为 0
+  parent:
+    title: 移动端
+    order: 1
+---
+```
+
+最后，在创建约定式二级导航时，还有一些规则是需要我们注意的：
+
+1. 在相同一级路径下，二级及三级路径存在 2 组及以上时才能形成二级导航，比如上述例子中如果 `mobile` 文件夹不存在，则不会形成二级导航，但倘若添加 `platforms/xxx.md` 又可以形成二级导航；
+2. 在相同一级路径下，如果仅存在三级路径，则只展示下拉菜单，一级导航本身不带超链，比如上述例子中的 `Platforms` 导航就不带超链；
+3. 在相同一级路径下，在 2 的基础上还存在二级或一级路径，则一级导航除了下拉菜单外也带超链，比如上述例子中如果添加 `platforms/xx.md` 则 `Platforms` 带超链；
+4. 不同级导航之间的侧边菜单是完全隔离的，比如上述例子中 `Platforms`、`Pc`、`Mobile` 都拥有不同的菜单；
+5. 资产路由本身不支持嵌套，但我们仍然可以通过 [`resolve.atomDirs[n].subType`](../config/index.md#resolve) 配置项实现二级导航，比如 `[{ type: 'component', subType: 'pc' dir: 'src' }]` 会为 `src/xx/index.md` 生成 `/components/pc/xx` 路由，以满足二级导航的路径规则。
 
 ## 菜单归类及生成
 

docs/guide/faq.md

@@ -204,3 +204,7 @@ import './index.css';
 ```
 
 这样无论是 dumi 还是实际项目里，都不需要做额外配置，但这种做法也有一些限制：如果引入的是 `.less`，那么目标项目的开发框架必须支持编译 Less。
+
+## 是否支持三级导航？
+
+不支持。如果文档目录结构的复杂度超过 3 级，应该考虑优化文档整体结构而非使用三级导航。如果有特殊场景需要，可以自定义主题实现。

src/client/theme-api/types.ts

@@ -61,7 +61,13 @@ export interface IRouteMeta {
     description?: string;
     keywords?: string[];
     // render related
-    nav?: string | { title?: string; order?: number };
+    nav?:
+      | string
+      | {
+          title?: string;
+          order?: number;
+          parent?: Omit<IRouteMeta['frontmatter']['nav'], 'parent'>;
+        };
     group?: string | { title?: string; order?: number };
     order?: number;
     hero?: {
@@ -146,7 +152,7 @@ export type ILocalesConfig = ILocale[];
 
 export interface INavItem {
   title: string;
-  link: string;
+  link?: string;
   order?: number;
   activePath?: string;
   [key: string]: any;

src/client/theme-api/useNavData.ts

@@ -1,13 +1,34 @@
 import { useFullSidebarData, useLocale, useSiteData } from 'dumi';
 import { useState } from 'react';
-import type { INavItems, IUserNavItems, IUserNavMode } from './types';
+import type {
+  INavItems,
+  ISidebarGroup,
+  IUserNavItems,
+  IUserNavMode,
+} from './types';
 import {
   getLocaleNav,
   pickRouteSortMeta,
   useLocaleDocRoutes,
   useRouteDataComparer,
 } from './utils';
 
+type INavSortMeta = Partial<Pick<INavItems[0], 'order' | 'title'>>;
+
+function genNavItem(
+  meta: INavSortMeta,
+  groups: ISidebarGroup[],
+  activePath: string,
+  link?: string,
+): INavItems[0] {
+  return {
+    title: meta.title || groups[0].title || groups[0].children[0].title,
+    order: meta.order || 0,
+    activePath: activePath,
+    ...(link ? { link } : {}),
+  };
+}
+
 /**
  * hook for get nav data
  */
@@ -37,28 +58,80 @@ export const useNavData = () => {
     }
 
     // fallback to generate nav data from sidebar data
-    const data = Object.entries(sidebar).map<INavItems[0]>(([link, groups]) => {
-      const meta = Object.values(routes).reduce<{
-        title?: string;
-        order?: number;
-      }>((ret, route) => {
-        // find routes which within the nav path
-        if (route.path!.startsWith(link.slice(1))) {
-          pickRouteSortMeta(ret, 'nav', route.meta!.frontmatter);
-        }
-        return ret;
-      }, {});
+    const data = Object.values(
+      Object.entries(sidebar)
+        // make sure shallow nav item before deep
+        .sort(([a], [b]) => a.split('/').length - b.split('/').length)
+        // convert sidebar data to nav data
+        .reduce<Record<string, INavItems[0]>>((ret, [link, groups]) => {
+          const [, parentPath, restPath] = link.match(/^(\/[^/]+)([^]+)?$/)!;
+          const isNestedNav = Boolean(restPath);
+          const [rootMeta, parentMeta] = Object.values(routes).reduce<
+            {
+              title?: string;
+              order?: number;
+            }[]
+          >(
+            (ret, route) => {
+              // find routes which within the nav path
+              if (route.path!.startsWith(link.slice(1))) {
+                pickRouteSortMeta(ret[0], 'nav', route.meta!.frontmatter);
+                // generate parent meta for nested nav
+                if (isNestedNav)
+                  pickRouteSortMeta(
+                    ret[1],
+                    'nav.parent',
+                    route.meta!.frontmatter,
+                  );
+              }
+              return ret;
+            },
+            [{}, {}],
+          );
 
-      return {
-        title: meta.title || groups[0].title || groups[0].children[0].title,
-        order: meta.order || 0,
-        link: groups[0].children[0].link,
-        activePath: link,
-      };
-    });
+          if (isNestedNav) {
+            // fallback to use parent path as title
+            parentMeta.title ??= parentPath
+              .slice(1)
+              .replace(/^[a-z]/, (s) => s.toUpperCase());
+
+            // handle nested nav item as parent children
+            const parent = (ret[parentPath] ??= genNavItem(
+              parentMeta,
+              groups,
+              parentPath,
+            ));
+
+            parent.children ??= [];
+            ret[parentPath].children!.push(
+              genNavItem(rootMeta, groups, link, groups[0].children[0].link),
+            );
+          } else {
+            // handle root nav item
+            ret[link] = genNavItem(
+              rootMeta,
+              groups,
+              link,
+              groups[0].children[0].link,
+            );
+          }
 
+          return ret;
+        }, {}),
+    );
+
+    data.forEach((item, i) => {
+      if (!item.link && item.children?.length === 1) {
+        // hoist nav item if only one child
+        data[i] = item.children[0];
+      } else if (item.children) {
+        // sort nav item children by order or title
+        item.children.sort(sidebarDataComparer);
+      }
+    });
+    // sort nav items by order or title
     data.sort(sidebarDataComparer);
-    // TODO: 2-level nav data
+
     if (mode === 'prepend') data.unshift(...userNavValue);
     else if (mode === 'append') data.push(...userNavValue);
 

src/client/theme-api/useSidebarData.ts

@@ -1,4 +1,4 @@
-import { useLocale, useLocation, useSiteData } from 'dumi';
+import { useLocale, useLocation, useRouteMeta, useSiteData } from 'dumi';
 import { useState } from 'react';
 import type {
   ILocalesConfig,
@@ -20,6 +20,25 @@ const getLocaleClearPath = (routePath: string, locale: ILocalesConfig[0]) => {
     : routePath;
 };
 
+/**
+ * get parent path from route path
+ */
+function getRouteParentPath(path: string, isIndexRoute?: boolean) {
+  const paths = path.split('/');
+  const sliceEnd = Math.min(
+    Math.max(
+      // increase 1 level if route file is index.md
+      isIndexRoute ? paths.length : paths.length - 1,
+      // least 1-level
+      1,
+    ),
+    // up to 2-level
+    2,
+  );
+
+  return paths.slice(0, sliceEnd).join('/');
+}
+
 /**
  * hook for get sidebar data for all nav
  */
@@ -40,12 +59,19 @@ export const useFullSidebarData = () => {
       // skip index routes
       if (clearPath && route.meta) {
         // extract parent path from route path
-        // a => /a
-        // en-US/a => /en-US/a
-        // a/b => /a
-        // en-US/a/b => /en-US/a
+        // normal examples:
+        //   a => /a
+        //   en-US/a => /en-US/a
+        //   a/b => /a
+        //   en-US/a/b => /en-US/a
+        // convention 2-level navs examples:
+        //   a/b => /a/b (if route file is a/b/index.md)
+        //   a/b/c => /a/b
         const parentPath = `/${route.path!.replace(clearPath, (s) =>
-          s.replace(/\/[^/]+$/, ''),
+          getRouteParentPath(
+            s,
+            route.meta!.frontmatter.filename?.endsWith('index.md'),
+          ),
         )}`;
         const { title, order } = pickRouteSortMeta(
           { order: 0 },
@@ -176,6 +202,7 @@ export const useSidebarData = () => {
   const locale = useLocale();
   const sidebar = useFullSidebarData();
   const { pathname } = useLocation();
+  const { frontmatter } = useRouteMeta();
   const clearPath = getLocaleClearPath(pathname.slice(1), locale);
   // extract parent path from location pathname
   // /a => /a
@@ -185,7 +212,7 @@ export const useSidebarData = () => {
   // /en-US/a/b/ => /en-US/a (also strip trailing /)
   const parentPath = clearPath
     ? pathname.replace(clearPath, (s) =>
-        s.replace(/([^/]+)(\/[^/]+\/?)$/, '$1'),
+        getRouteParentPath(s, frontmatter.filename?.endsWith('index.md')),
       )
     : pathname;
 

src/client/theme-api/utils.ts

@@ -108,10 +108,15 @@ export const useRouteDataComparer = <
  */
 export const pickRouteSortMeta = (
   original: Partial<Pick<INavItem, 'order' | 'title'>>,
-  field: 'nav' | 'group',
+  field: 'nav' | 'nav.parent' | 'group',
   fm: IRouteMeta['frontmatter'],
 ) => {
-  const sub = fm[field];
+  const sub: IRouteMeta['frontmatter']['group'] =
+    field === 'nav.parent'
+      ? typeof fm.nav === 'object'
+        ? fm.nav.parent
+        : {}
+      : fm[field];
 
   switch (typeof sub) {
     case 'object':