feat: support overviewDepth to control the minimum title displayed in…

… the overview page

.changeset/loud-cameras-occur.md

@@ -0,0 +1,7 @@
+---
+"@rspress/plugin-auto-nav-sidebar": minor
+"@rspress/theme-default": minor
+"@rspress/shared": minor
+---
+
+support overviewDepth to control the minimum title displayed in the overview page

packages/document/docs/en/guide/basic/auto-nav-sidebar.mdx

@@ -70,13 +70,17 @@ export type SideMetaItem =
       type: 'file';
       name: string;
       label?: string;
+      tag?: string;
+      overviewDepth?: 'h1' | 'h2';
     }
   | {
       type: 'dir';
       name: string;
       label?: string;
       collapsible?: boolean;
       collapsed?: boolean;
+      tag?: string;
+      overviewDepth?: 'h1' | 'h2';
     }
   | {
       type: 'divider';
@@ -105,10 +109,11 @@ In the case of describing **file**, the types are as follows:
   type: 'file';
   name: string;
   label?: string;
+  overviewDepth?: 'h1' | 'h2';
 }
 ```
 
-Among them, `name` means the file name, `with`/`without` suffix is ​​supported, `label` means the display name of the file in the sidebar.`label` is an optional value, if it is not filled, it will automatically take the h1 title in the document. For example:
+Among them, `name` means the file name, `with`/`without` suffix is ​​supported, `label` means the display name of the file in the sidebar.`label` is an optional value, if it is not filled, it will automatically take the h1 title in the document. `overviewDepth` means the minimum title displayed in the overview page of the file. It is an optional value and the default value is h2. For example:
 
 ```json
 {
@@ -127,10 +132,11 @@ In the case of describing **directories**, the types are as follows:
   label?: string;
   collapsible?: boolean;
   collapsed?: boolean;
+  overviewDepth?: 'h1' | 'h2';
 }
 ```
 
-Among them, `name` indicates the directory name, `label` indicates the display name of the directory in the sidebar, `collapsible` indicates whether the directory can be collapsed, and `collapsed` indicates whether the directory is collapsed by default, for example:
+Among them, `name` indicates the directory name, `label` indicates the display name of the directory in the sidebar, `collapsible` indicates whether the directory can be collapsed, `collapsed` indicates whether the directory is collapsed by default, and `overviewDepth` indicates the minimum title displayed on the overview page for files in this directory. It is an optional value and the default value is h2. For example:
 
 ```json
 {

packages/document/docs/en/guide/default-theme/overview-page.mdx

@@ -56,3 +56,5 @@ At the same time, the file `api/theme/_meta.json` has the following content:
 > The detailed configuration usage of `_meta.json` can be referred to [Auto Nav/Sidebar](/guide/basic/auto-nav-sidebar).
 
 In the above configuration, the final preview page will generate a group called `Theme`, which contains the h1, h2 titles of two articles: `component.md(x)` and `utils.md(x)`. Of course, you can also refer to the config of the `Theme` group to add more groups.
+
+If you want to control the minimum title displayed in the overview page, you can configure it through `overviewDepth` config in `_meta.json`, which defaults to h2.

packages/document/docs/zh/guide/basic/auto-nav-sidebar.mdx

@@ -71,6 +71,7 @@ export type SideMetaItem =
       name: string;
       label?: string;
       tag?: string;
+      overviewDepth?: 'h1' | 'h2';
     }
   | {
       type: 'dir';
@@ -79,6 +80,7 @@ export type SideMetaItem =
       collapsible?: boolean;
       collapsed?: boolean;
       tag?: string;
+      overviewDepth?: 'h1' | 'h2';
     }
   | {
       type: 'divider';
@@ -112,10 +114,11 @@ export type SideMetaItem =
   type: 'file';
   name: string;
   label?: string;
+  overviewDepth?: 'h1' | 'h2';
 }
 ```
 
-其中，`name` 表示文件名，同时支持`带`/`不带`后缀，`label` 表示该文件在侧边栏中的显示名称，为可选值，如果未填则会自动取文档中的 h1 标题。比如:
+其中，`name` 表示文件名，同时支持`带`/`不带`后缀，`label` 表示该文件在侧边栏中的显示名称，为可选值，如果未填则会自动取文档中的 h1 标题。`overviewDepth` 表示该文件在预览页中展示的最小标题，为可选值，默认为 h2。比如:
 
 ```json
 {
@@ -134,10 +137,11 @@ export type SideMetaItem =
   label: string;
   collapsible?: boolean;
   collapsed?: boolean;
+  overviewDepth?: 'h1' | 'h2';
 }
 ```
 
-其中，`name` 表示目录名，`label` 表示该目录在侧边栏中的显示名称，`collapsible` 表示该目录是否可以折叠，`collapsed` 表示该目录是否默认折叠，比如:
+其中，`name` 表示目录名，`label` 表示该目录在侧边栏中的显示名称，`collapsible` 表示该目录是否可以折叠，`collapsed` 表示该目录是否默认折叠，`overviewDepth` 表示该目录下的文件在预览页中展示的最小标题，为可选值，默认为 h2。比如:
 
 ```json
 {

packages/document/docs/zh/guide/default-theme/overview-page.mdx

@@ -56,3 +56,5 @@ overview: true
 > `_meta.json` 的详细配置用法可以参考[自动化导航栏/侧边栏](/guide/basic/auto-nav-sidebar)。
 
 在如上的配置中，最后预览页会生成一个 `Theme` 的分组，这个分组里面包含 `component.md(x)` 和 `utils.md(x)` 两篇文章的 h1、h2 标题。当然，你也可以参考 `Theme` 分组的配置，添加更多的分组。
+
+如果要控制在预览页中展示的最小标题，可以通过 `_meta.json` 中的 `overviewDepth` 配置，默认为 h2。

packages/plugin-auto-nav-sidebar/src/type.ts

@@ -1,4 +1,4 @@
-import { Nav } from '@rspress/shared';
+import { Nav, type OverViewDepth } from '@rspress/shared';
 
 export type NavMeta = Nav;
 
@@ -14,6 +14,7 @@ export type SideMetaItem =
       collapsed?: boolean;
       tag?: string;
       dashed?: boolean;
+      overviewDepth?: OverViewDepth;
     };
 
 export type SideMeta = SideMetaItem[];

packages/plugin-auto-nav-sidebar/src/walk.ts

@@ -84,6 +84,7 @@ export async function scanSideMeta(
         link,
         tag,
         dashed,
+        overviewDepth,
       } = metaItem;
       // when type is divider, name maybe undefined, and link is not used
       const pureLink = `${relativePath}/${name?.replace(/\.mdx?$/, '')}`;
@@ -95,6 +96,7 @@ export async function scanSideMeta(
           text: title,
           link: addRoutePrefix(pureLink),
           tag,
+          overviewDepth,
           _fileKey: realPath ? path.relative(docsDir, realPath) : '',
         };
       }
@@ -115,6 +117,7 @@ export async function scanSideMeta(
           items: subSidebar,
           link: realPath ? addRoutePrefix(pureLink) : '',
           tag,
+          overviewDepth,
           _fileKey: realPath ? path.relative(docsDir, realPath) : '',
         };
       }

packages/shared/src/types/defaultTheme.ts

@@ -163,6 +163,9 @@ export interface NavItemWithLinkAndChildren {
 // image -----------------------------------------------------------------------
 export type Image = string | { src: string; alt?: string };
 
+// overview -----------------------------------------------------------------------
+export type OverViewDepth = 'h1' | 'h2';
+
 // sidebar -------------------------------------------------------------------
 export interface Sidebar {
   [path: string]: (
@@ -184,6 +187,7 @@ export interface SidebarGroup {
    * For hmr usage in development
    */
   _fileKey?: string;
+  overviewDepth?: OverViewDepth;
 }
 
 export type SidebarItem = {
@@ -194,6 +198,7 @@ export type SidebarItem = {
    * For hmr usage in development
    */
   _fileKey?: string;
+  overviewDepth?: OverViewDepth;
 };
 
 export type SidebarDivider = { dividerType: 'dashed' | 'solid' };

packages/theme-default/src/components/Overview/index.tsx

@@ -61,7 +61,16 @@ export function Overview(props: {
   const { items: overviewSidebarGroups } = useSidebarData() as {
     items: (NormalizedSidebarGroup | SidebarItem)[];
   };
-  function normalizeSidebarItem(item: NormalizedSidebarGroup | SidebarItem) {
+  function normalizeSidebarItem(
+    item: SidebarItem | SidebarDivider | NormalizedSidebarGroup,
+    sidebarGroup?: NormalizedSidebarGroup,
+  ) {
+    if ('dividerType' in item) {
+      return item;
+    }
+    const overviewDepth =
+      item.overviewDepth ?? sidebarGroup?.overviewDepth ?? 'h2';
+    const headerDepth = Number(overviewDepth.replace('h', ''));
     // sidebar items link without base path
     const pageModule = overviewModules.find(m =>
       isEqualPath(m.routePath, withBase(item.link || '')),
@@ -70,7 +79,8 @@ export function Overview(props: {
     return {
       ...item,
       link,
-      headers: pageModule?.toc?.filter(header => header.depth === 2) || [],
+      headers:
+        pageModule?.toc?.filter(header => header.depth === headerDepth) || [],
     };
   }
   const groups =
@@ -89,7 +99,12 @@ export function Overview(props: {
         .map(sidebarGroup => ({
           name: sidebarGroup.text || '',
           items: (sidebarGroup as NormalizedSidebarGroup).items
-            .map(normalizeSidebarItem)
+            .map(item =>
+              normalizeSidebarItem(
+                item,
+                sidebarGroup as NormalizedSidebarGroup,
+              ),
+            )
             .filter(Boolean),
         })) as Group[];
       const singleLinks = overviewSidebarGroups.filter(
@@ -101,7 +116,7 @@ export function Overview(props: {
           ? [
               {
                 name: defaultGroupTitle,
-                items: singleLinks.map(normalizeSidebarItem),
+                items: singleLinks.map(item => normalizeSidebarItem(item)),
               },
             ]
           : []),