chore: use overviewHeaders

.changeset/loud-cameras-occur.md

@@ -1,7 +1,7 @@
 ---
-"@rspress/plugin-auto-nav-sidebar": minor
-"@rspress/theme-default": minor
-"@rspress/shared": minor
+'@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
+feat: support overviewHeaders to control the minimum title displayed in the overview page

e2e/fixtures/auto-nav-sidebar/doc/api/_meta.json

@@ -8,7 +8,7 @@
     "type": "dir",
     "name": "config",
     "label": "Config",
-    "overviewDepth": "h2"
+    "overviewHeaders": [2]
   },
   {
     "type": "dir",

e2e/fixtures/auto-nav-sidebar/doc/api/client-api/_meta.json

@@ -7,7 +7,7 @@
   {
     "type": "file",
     "name": "api-runtime",
-    "overviewDepth": "h1"
+    "overviewHeaders": []
   },
   "api-components"
 ]

e2e/fixtures/auto-nav-sidebar/doc/api/config/_meta.json

@@ -5,6 +5,6 @@
   {
     "type": "file",
     "name": "config-build",
-    "overviewDepth": "h1"
+    "overviewHeaders": [2, 3]
   }
 ]

e2e/fixtures/auto-nav-sidebar/doc/api/config/config-frontmatter.mdx

@@ -1,3 +1,7 @@
+---
+overviewHeaders: []
+---
+
 # Front Matter 配置
 
 ## title

e2e/tests/auto-nav-sidebar.test.ts

@@ -70,8 +70,10 @@ test.describe('Auto nav and sidebar test', async () => {
         'logoText',
         'nav',
         'sidebar',
-        'title',
-        'description',
+        'builderConfig',
+        '默认配置',
+        'markdown',
+        'markdown.remarkPlugins',
         '用法',
         '示例',
         'rspress dev',
@@ -100,7 +102,16 @@ test.describe('Auto nav and sidebar test', async () => {
     const a = await page.$$('.overview-group_8f375 ul a');
     const aTexts = await Promise.all(a.map(element => element.textContent()));
     expect(aTexts.join(',')).toEqual(
-      ['root', 'logoText', 'nav', 'sidebar', 'title', 'description'].join(','),
+      [
+        'root',
+        'logoText',
+        'nav',
+        'sidebar',
+        'builderConfig',
+        '默认配置',
+        'markdown',
+        'markdown.remarkPlugins',
+      ].join(','),
     );
   });
 

packages/document/docs/en/api/config/config-frontmatter.mdx

@@ -185,3 +185,24 @@ Whether to hide the top navigation bar. You can hide the top nav bar with the fo
 navbar: true
 ---
 ```
+
+## overviewHeaders
+
+- Type: `number[]`
+- Default: `[2]`
+
+The headers shown in the overview page. By default, the displayed header is h2. But if you want to display different headers, you can specify it using the `overviewHeaders` Front Matter field. For example:
+
+```yaml
+---
+overviewHeaders: []
+---
+```
+
+Or
+
+```yaml
+---
+overviewHeaders: [2, 3]
+---
+```

packages/document/docs/en/fragments/internal-components.mdx

@@ -147,8 +147,8 @@ export interface OverviewProps {
   groups?: Group[];
   // default title
   defaultGroupTitle?: string;
-  // minimum title displayed in the overview page of the file
-  overviewDepth?: 'h1' | 'h2';
+  // headers displayed in the overview page of the file
+  overviewHeaders?: number[];
 }
 ```
 

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

@@ -71,7 +71,7 @@ export type SideMetaItem =
       name: string;
       label?: string;
       tag?: string;
-      overviewDepth?: 'h1' | 'h2';
+      overviewHeaders?: number[];
     }
   | {
       type: 'dir';
@@ -80,7 +80,7 @@ export type SideMetaItem =
       collapsible?: boolean;
       collapsed?: boolean;
       tag?: string;
-      overviewDepth?: 'h1' | 'h2';
+      overviewHeaders?: number[];
     }
   | {
       type: 'divider';
@@ -109,11 +109,11 @@ In the case of describing **file**, the types are as follows:
   type: 'file';
   name: string;
   label?: string;
-  overviewDepth?: 'h1' | 'h2';
+  overviewHeaders?: number[];
 }
 ```
 
-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:
+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. `overviewHeaders` means the headers displayed in the overview page of the file. It is an optional value and the default value is `[2]`. For example:
 
 ```json
 {
@@ -132,11 +132,11 @@ In the case of describing **directories**, the types are as follows:
   label?: string;
   collapsible?: boolean;
   collapsed?: boolean;
-  overviewDepth?: 'h1' | 'h2';
+  overviewHeaders?: number[];
 }
 ```
 
-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:
+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 `overviewHeaders` indicates the headers displayed on the overview page for files in this directory. It is an optional value and the default value is `[2]`. For example:
 
 ```json
 {

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

@@ -62,7 +62,7 @@ At the same time, the file `api/theme/_meta.json` has the following content:
 
 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.
+If you want to control the headers displayed in the overview page, you can configure it through `overviewHeaders` config in `_meta.json`, which defaults to `[2]`. If it's a single file, you can also configure FrontMatter with `overviewHeaders: [2]`.
 
 If you want to generate a sub-preview page under `theme`, there are two ways:
 

packages/document/docs/zh/api/config/config-frontmatter.mdx

@@ -185,3 +185,24 @@ footer: false
 navbar: false
 ---
 ```
+
+## overviewHeaders
+
+- Type: `number[]`
+- Default: `[2]`
+
+在预览页中展示的标题级别。默认情况下，展示的标题为 h2。但是如果你想展示不同的标题级别，你可以使用 `overviewHeaders` 这个 Front Matter 字段来指定。例如：
+
+```yaml
+---
+overviewHeaders: []
+---
+```
+
+或者
+
+```yaml
+---
+overviewHeaders: [2, 3]
+---
+```

packages/document/docs/zh/fragments/internal-components.mdx

@@ -148,8 +148,8 @@ export interface OverviewProps {
   groups?: Group[];
   // 默认标题
   defaultGroupTitle?: string;
-  // 在预览页中展示的最小标题
-  overviewDepth?: 'h1' | 'h2';
+  // 在预览页中展示的标题级别
+  overviewHeaders?: number[];
 }
 ```
 

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

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

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

@@ -62,7 +62,7 @@ overview: true
 
 在如上的配置中，最后预览页会生成一个 `Theme` 的分组，这个分组里面包含 `component.md(x)` 和 `utils.md(x)` 两篇文章的 h1、h2 标题。当然，你也可以参考 `Theme` 分组的配置，添加更多的分组。
 
-如果要控制在预览页中展示的最小标题，可以通过 `_meta.json` 中的 `overviewDepth` 配置，默认为 h2。
+如果要控制在预览页中展示的标题级别，可以通过 `_meta.json` 中的 `overviewHeaders` 配置，默认为 `[2]`。如果针对单个文件，也可以配置 `overviewHeaders: [2]` 的 FrontMatter。
 
 如果要在 `theme` 下同样生成一个子预览页，有以下两种方式：
 

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

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

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

@@ -20,10 +20,10 @@ export async function detectFilePath(rawPath: string) {
   return realPath;
 }
 
-export async function extractH1Title(
+export async function extractTitleAndOverviewHeaders(
   filePath: string,
   rootDir: string,
-): Promise<string> {
+): Promise<{ title: string; overviewHeaders: string | undefined }> {
   const realPath = await detectFilePath(filePath);
   if (!realPath) {
     logger.warn(
@@ -32,14 +32,20 @@ export async function extractH1Title(
         '_meta.json',
       )}".`,
     );
-    return '';
+    return {
+      title: '',
+      overviewHeaders: undefined,
+    };
   }
   const content = await fs.readFile(realPath, 'utf-8');
   const fileNameWithoutExt = path.basename(realPath, path.extname(realPath));
   const h1RegExp = /^#\s+(.*)$/m;
   const match = content.match(h1RegExp);
   const { frontmatter } = loadFrontMatter(content, filePath, rootDir);
-  return frontmatter.title || match?.[1] || fileNameWithoutExt;
+  return {
+    title: frontmatter.title || match?.[1] || fileNameWithoutExt,
+    overviewHeaders: frontmatter.overviewHeaders,
+  };
 }
 
 export function combineWalkResult(

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

@@ -12,7 +12,7 @@ import {
   SidebarSectionHeader,
 } from '@rspress/shared';
 import { NavMeta, SideMeta } from './type';
-import { detectFilePath, extractH1Title } from './utils';
+import { detectFilePath, extractTitleAndOverviewHeaders } from './utils';
 
 export async function scanSideMeta(
   workDir: string,
@@ -63,14 +63,15 @@ export async function scanSideMeta(
   )[] = await Promise.all(
     sideMeta.map(async metaItem => {
       if (typeof metaItem === 'string') {
-        const title = await extractH1Title(
+        const { title, overviewHeaders } = await extractTitleAndOverviewHeaders(
           path.resolve(workDir, metaItem),
           rootDir,
         );
         const pureLink = `${relativePath}/${metaItem.replace(/\.mdx?$/, '')}`;
         return {
           text: title,
           link: addRoutePrefix(pureLink),
+          overviewHeaders,
           _fileKey: path.relative(docsDir, path.join(workDir, metaItem)),
         };
       }
@@ -84,19 +85,24 @@ export async function scanSideMeta(
         link,
         tag,
         dashed,
-        overviewDepth,
+        overviewHeaders,
       } = metaItem;
       // when type is divider, name maybe undefined, and link is not used
       const pureLink = `${relativePath}/${name?.replace(/\.mdx?$/, '')}`;
       if (type === 'file') {
-        const title =
-          label || (await extractH1Title(path.resolve(workDir, name), rootDir));
+        const titleAndOverviewHeaders = await extractTitleAndOverviewHeaders(
+          path.resolve(workDir, name),
+          rootDir,
+        );
+        const title = label || titleAndOverviewHeaders.title;
         const realPath = await detectFilePath(path.resolve(workDir, name));
         return {
           text: title,
           link: addRoutePrefix(pureLink),
           tag,
-          overviewDepth,
+          overviewHeaders: titleAndOverviewHeaders.overviewHeaders
+            ? titleAndOverviewHeaders.overviewHeaders
+            : overviewHeaders,
           _fileKey: realPath ? path.relative(docsDir, realPath) : '',
         };
       }
@@ -117,7 +123,7 @@ export async function scanSideMeta(
           items: subSidebar,
           link: realPath ? addRoutePrefix(pureLink) : '',
           tag,
-          overviewDepth,
+          overviewHeaders,
           _fileKey: realPath ? path.relative(docsDir, realPath) : '',
         };
       }