fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars and place index.md at the top (#3171)

SoonIter · web-flow · commit e64a8783e334 · 2026-03-02T13:27:30.000Z
diff --git a/e2e/fixtures/auto-nav-sidebar-issue-1682/index.test.ts b/e2e/fixtures/auto-nav-sidebar-issue-1682/index.test.ts
@@ -27,7 +27,7 @@ test.describe('Auto nav and sidebar dir issue-1682', async () => {
     const sidebarTexts = await getSidebarTexts(page);
     expect(sidebarTexts.length).toBe(3);
     expect(sidebarTexts.join(',')).toEqual(
-      ['Second sub-directory', 'test', 'First sub-directory'].join(','),
+      ['First sub-directory', 'Second sub-directory', 'test'].join(','),
     );
   });
 });
diff --git a/e2e/fixtures/auto-nav-sidebar-no-meta/index.test.ts b/e2e/fixtures/auto-nav-sidebar-no-meta/index.test.ts
@@ -24,6 +24,7 @@ test.describe('Auto nav and sidebar test', async () => {
 
     const sidebarTexts = await getSidebarTexts(page);
     expect(sidebarTexts).toEqual([
+      'HomePage',
       'API',
       'plugin',
       'Plugin a',
@@ -34,7 +35,6 @@ test.describe('Auto nav and sidebar test', async () => {
       'Build config',
       'Front matter config',
       'Theme config',
-      'HomePage',
     ]);
   });
 
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/_nav.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/_nav.json
@@ -0,0 +1 @@
+[{ "text": "Guide", "link": "/guide/", "activeMatch": "^/guide/" }]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/_meta.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/_meta.json
@@ -0,0 +1 @@
+["a", "b", "excluded-file"]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/a.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/a.md
@@ -0,0 +1,3 @@
+---
+title: Page a
+---
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/asset/a.svg b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/asset/a.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"></svg>
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/b.mdx b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/b.mdx
@@ -0,0 +1,3 @@
+---
+title: Page b
+---
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/excluded-file.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/excluded-file.md
@@ -0,0 +1,3 @@
+---
+title: Excluded
+---
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/_components/Button.mdx b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/_components/Button.mdx
@@ -0,0 +1 @@
+# Button
diff --git a/packages/core/src/node/auto-nav-sidebar/normalize.ts b/packages/core/src/node/auto-nav-sidebar/normalize.ts
@@ -12,6 +12,7 @@ import { logger } from '@rspress/shared/logger';
 import picocolors from 'picocolors';
 import { PUBLIC_DIR } from '../constants';
 import { absolutePathToRoutePath, addRoutePrefix } from '../route/RoutePage';
+import { RouteService } from '../route/RouteService';
 import { createError } from '../utils';
 import type {
   CustomLinkMeta,
@@ -43,7 +44,16 @@ async function fsDirToMetaItems(
 ): Promise<SideMetaItem[]> {
   let subItems: string[];
   try {
-    subItems = await readdir(workDir);
+    subItems = (await readdir(workDir)).sort((a, b) => {
+      // 1. index.md or index.mdx should be placed at the top of the sidebar
+      const aIsIndex = a.replace(/\.[^/.]+$/, '') === 'index';
+      const bIsIndex = b.replace(/\.[^/.]+$/, '') === 'index';
+      if (aIsIndex !== bIsIndex) {
+        return aIsIndex ? -1 : 1;
+      }
+      // 2. Dictionary order
+      return a.localeCompare(b);
+    });
   } catch (e) {
     const metaFilePath = join(workDir, '_meta.json');
 
@@ -100,6 +110,7 @@ async function metaItemToSidebarItem(
 ): Promise<
   | (SidebarItem | SidebarGroup | SidebarDivider | SidebarSectionHeader)
   | (SidebarItem | SidebarGroup | SidebarDivider | SidebarSectionHeader)[]
+  | null
 > {
   if (typeof metaItem === 'string') {
     return metaFileItemToSidebarItem(
@@ -123,7 +134,7 @@ async function metaItemToSidebarItem(
   }
 
   if (type === 'dir') {
-    return metaDirItemToSidebarItem(
+    const group = await metaDirItemToSidebarItem(
       metaItem,
       workDir,
       docsDir,
@@ -132,17 +143,26 @@ async function metaItemToSidebarItem(
       mdFileSet,
       false,
     );
+    if (group.items.length === 0 && !group.link) {
+      return null;
+    }
+    return group;
   }
 
   if (type === 'dir-section-header') {
-    return metaDirSectionHeaderItemToSidebarItem(
+    const items = await metaDirSectionHeaderItemToSidebarItem(
       metaItem,
       workDir,
       docsDir,
       extensions,
       metaFileSet,
       mdFileSet,
     );
+    // If only the section header remains (no child items), prune it
+    if (items.length <= 1) {
+      return null;
+    }
+    return items;
   }
 
   if (type === 'custom-link') {
@@ -184,7 +204,7 @@ async function metaFileItemToSidebarItem(
   docsDir: string,
   extensions: string[],
   mdFileSet: Set<string>,
-): Promise<SidebarItem> {
+): Promise<SidebarItem | null> {
   let metaItem: FileSideMeta | null = null;
   if (typeof metaItemRaw === 'string') {
     metaItem = {
@@ -218,6 +238,10 @@ async function metaFileItemToSidebarItem(
   }
 
   const link = absolutePathToRoutePath(absolutePathWithExt, docsDir);
+  const routeService = RouteService.getInstance();
+  if (routeService?.isExistRoute && !routeService.isExistRoute(link)) {
+    return null;
+  }
   const info = await extractInfoFromFrontmatterWithAbsolutePath(
     absolutePathWithExt,
     docsDir,
@@ -294,7 +318,12 @@ async function metaDirItemToSidebarItem(
         ),
       ),
     );
-    return items.flat();
+    return items.flat().filter(Boolean) as (
+      | SidebarItem
+      | SidebarGroup
+      | SidebarDivider
+      | SidebarSectionHeader
+    )[];
   }
 
   try {
@@ -310,6 +339,10 @@ async function metaDirItemToSidebarItem(
       mdFileSet,
     );
 
+    if (!sameNameFile) {
+      throw new Error(`Excluded route: ${name}`);
+    }
+
     const { link, text, _fileKey, context, overviewHeaders, tag } =
       sameNameFile;
     return {
@@ -357,6 +390,18 @@ async function metaDirItemToSidebarItem(
         mdFileSet,
       );
 
+      if (!indexFile) {
+        return {
+          text: label || name,
+          collapsible,
+          collapsed,
+          items: await getItems(),
+          overviewHeaders: metaJsonOverviewHeaders,
+          context: metaJsonContext,
+          _fileKey: getFileKey(dirAbsolutePath, docsDir),
+        } satisfies SidebarGroup;
+      }
+
       const { link, text, _fileKey, context, overviewHeaders, tag } = indexFile;
       return {
         text: label || text || name,
diff --git a/packages/core/src/node/auto-nav-sidebar/walk.test.ts b/packages/core/src/node/auto-nav-sidebar/walk.test.ts
@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { DEFAULT_PAGE_EXTENSIONS } from '@rspress/shared/constants';
-import { describe, expect, it } from '@rstest/core';
+import { afterEach, describe, expect, it } from '@rstest/core';
 import {
   getRoutePathParts,
   normalizeRoutePath,
@@ -25,7 +25,16 @@ function orderStringSet(input: Set<string>) {
   return Array.from(input).sort().join('\n');
 }
 
+const defaultMock = {
+  normalizeRoutePath: mockNormalizeRoutePath,
+  getRoutePathParts: mockGetRoutePathParts,
+} as RouteService;
+
 describe('walk', () => {
+  afterEach(() => {
+    RouteService.__instance__ = defaultMock;
+  });
+
   it('basic', async () => {
     const docsDir = path.join(__dirname, './fixtures/docs');
     const metaFileSet = new Set<string>();
@@ -156,12 +165,38 @@ describe('walk', () => {
         "nav": [],
         "sidebar": {
           "/": [
+            {
+              "_fileKey": "index",
+              "context": undefined,
+              "link": "/",
+              "overviewHeaders": undefined,
+              "tag": undefined,
+              "text": "HomePage",
+            },
             {
               "_fileKey": "api/index",
               "collapsed": undefined,
               "collapsible": undefined,
               "context": undefined,
               "items": [
+                {
+                  "_fileKey": "api/_components",
+                  "collapsed": undefined,
+                  "collapsible": undefined,
+                  "context": undefined,
+                  "items": [
+                    {
+                      "_fileKey": "api/_components/Button",
+                      "context": undefined,
+                      "link": "/api/_components/Button",
+                      "overviewHeaders": undefined,
+                      "tag": undefined,
+                      "text": "Button",
+                    },
+                  ],
+                  "overviewHeaders": undefined,
+                  "text": "_components",
+                },
                 {
                   "_fileKey": "api/api",
                   "context": undefined,
@@ -196,21 +231,14 @@ describe('walk', () => {
               "tag": undefined,
               "text": "No meta",
             },
-            {
-              "_fileKey": "index",
-              "context": undefined,
-              "link": "/",
-              "overviewHeaders": undefined,
-              "tag": undefined,
-              "text": "HomePage",
-            },
           ],
         },
       }
     `);
     expect(orderStringSet(metaFileSet)).toMatchInlineSnapshot(`""`);
     expect(orderStringSet(mdFileSet)).toMatchInlineSnapshot(`
-      "<ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/api.mdx
+      "<ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/_components/Button.mdx
+      <ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/api.mdx
       <ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/guide/getting-started.mdx
       <ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/guide/index.mdx
       <ROOT>/packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/index.mdx
@@ -304,6 +332,69 @@ describe('walk', () => {
     `);
   });
 
+  it('route.exclude should filter sidebar items', async () => {
+    const docsDir = path.join(__dirname, './fixtures/docs-no-meta');
+    const metaFileSet = new Set<string>();
+    const mdFileSet = new Set<string>();
+
+    // Mock isExistRoute to exclude _components paths
+    RouteService.__instance__ = {
+      normalizeRoutePath: mockNormalizeRoutePath,
+      getRoutePathParts: mockGetRoutePathParts,
+      isExistRoute: (link: string) => !link.includes('_components'),
+    } as RouteService;
+
+    const result = await walk(
+      docsDir,
+      docsDir,
+      DEFAULT_PAGE_EXTENSIONS,
+      metaFileSet,
+      mdFileSet,
+    );
+
+    // _components/Button should NOT appear in sidebar
+    const allLinks = JSON.stringify(result.sidebar);
+    expect(allLinks).not.toContain('_components');
+    expect(allLinks).not.toContain('Button');
+
+    // Other items should still be present
+    expect(allLinks).toContain('getting-started');
+
+    // Excluded files should not be in mdFileSet
+    expect(Array.from(mdFileSet).some(f => f.includes('Button'))).toBe(false);
+  });
+
+  it('_meta.json referencing excluded file should skip it', async () => {
+    const docsDir = path.join(__dirname, './fixtures/docs-exclude-meta');
+    const metaFileSet = new Set<string>();
+    const mdFileSet = new Set<string>();
+
+    RouteService.__instance__ = {
+      normalizeRoutePath: mockNormalizeRoutePath,
+      getRoutePathParts: mockGetRoutePathParts,
+      isExistRoute: (link: string) => !link.includes('excluded-file'),
+    } as RouteService;
+
+    const result = await walk(
+      docsDir,
+      docsDir,
+      DEFAULT_PAGE_EXTENSIONS,
+      metaFileSet,
+      mdFileSet,
+    );
+
+    const sidebar = result.sidebar['/guide'];
+    const allLinks = JSON.stringify(sidebar);
+    expect(allLinks).not.toContain('excluded-file');
+    expect(allLinks).toContain('Page a');
+    expect(allLinks).toContain('Page b');
+
+    // Excluded files should not be in mdFileSet
+    expect(Array.from(mdFileSet).some(f => f.includes('excluded-file'))).toBe(
+      false,
+    );
+  });
+
   it('custom link group', async () => {
     const docsDir = path.join(__dirname, './fixtures/docs-custom-link-group');
     const metaFileSet = new Set<string>();

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+[{ "text": "Guide", "link": "/guide/", "activeMatch": "^/guide/" }]`