fix(plugin-auto-nav-sidebar): Exclude config.route.exclude files from auto-generated sidebar

.changeset/serious-clouds-tap.md

@@ -0,0 +1,6 @@
+---
+"@rspress/plugin-auto-nav-sidebar": patch
+"@rspress/docs": patch
+---
+
+Exclude config.route.exclude files from auto-generated sidebar

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

@@ -272,7 +272,9 @@ Here is a complete example using the three types above:
 
 ### No Config Usage
 
-In some directories, you don't need to configure `_meta.json` and let the framework automatically generate the sidebar. This requires ensuring that the directory contains only documents, not subdirectories, and you have no requirements for the order of documents. For example, there is now the following document structure:
+In some directories, you don't need to configure `_meta.json` and let the framework automatically generate the sidebar.
+
+For example, there is a document structure:
 
 ```bash
 docs
@@ -299,7 +301,9 @@ In the guides directory you can configure `_meta.json` as follows:
 ]
 ```
 
-In `basic` directory, you may not configure `_meta.json`, and then the framework will automatically generate a sidebar for you, the default is sorted alphabetically according to the file name. If you want to customize the order, you can prefix the file name with a number, such as:
+In `basic` directory, you may not configure `_meta.json`, and then the framework will automatically generate a sidebar for you.
+
+By default files are sorted alphabetically. If you want to customize their orders, you can prefix the file names with a number, such as:
 
 ```bash
 basic
@@ -308,6 +312,8 @@ basic
   └── 3-plugin-development.md
 ```
 
+> Note : The files defined in [route.exclude](/api/config/config-basic.html#routeexclude) won't appear in the auto-generated sidebar.
+
 ### Add SVG Icons Before Titles
 
 In addition, you can add icons before the title through the `tag` confing, like this:

packages/plugin-auto-nav-sidebar/package.json

@@ -48,6 +48,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@rspress/shared": "workspace:*"
+    "@rspress/shared": "workspace:*",
+    "globby": "11.1.0"
   }
 }

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

@@ -157,6 +157,7 @@ function processLocales(
   root: string,
   defaultLang: string,
   defaultVersion: string,
+  excludedFiles?: string[],
 ) {
   return Promise.all(
     langs.map(async lang => {
@@ -168,14 +169,20 @@ function processLocales(
                   lang === defaultLang ? '' : `/${lang}`
                 }`,
               );
-              return walk(path.join(root, version, lang), routePrefix, root);
+              return walk(
+                path.join(root, version, lang),
+                routePrefix,
+                root,
+                excludedFiles,
+              );
             }),
           )
         : [
             await walk(
               path.join(root, lang),
               addTrailingSlash(lang === defaultLang ? '' : `/${lang}`),
               root,
+              excludedFiles,
             ),
           ];
       return combineWalkResult(walks, versions);
@@ -203,6 +210,7 @@ export function pluginAutoNavSidebar(): RspressPlugin {
           config.root!,
           defaultLang,
           defaultVersion,
+          config.route?.exclude,
         );
         config.themeConfig.locales = config.themeConfig.locales.map(
           (item, index) => ({
@@ -230,10 +238,18 @@ export function pluginAutoNavSidebar(): RspressPlugin {
                   path.join(config.root!, version),
                   routePrefix,
                   config.root!,
+                  config.route?.exclude,
                 );
               }),
             )
-          : [await walk(config.root!, '/', config.root!)];
+          : [
+              await walk(
+                config.root!,
+                '/',
+                config.root!,
+                config.route?.exclude,
+              ),
+            ];
 
         const combined = combineWalkResult(walks, versions);
 

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

@@ -13,12 +13,14 @@ import {
 } from '@rspress/shared';
 import { NavMeta, SideMeta } from './type';
 import { detectFilePath, extractTitleAndOverviewHeaders } from './utils';
+import globby from 'globby';
 
 export async function scanSideMeta(
   workDir: string,
   rootDir: string,
   docsDir: string,
   routePrefix: string,
+  excludedFiles?: string[],
 ) {
   const addRoutePrefix = (link: string) => `${routePrefix}${link}`;
   // find the `_meta.json` file
@@ -32,7 +34,18 @@ export async function scanSideMeta(
     sideMeta = (await fs.readJSON(metaFile, 'utf8')) as SideMeta;
   } catch (e) {
     // If the `_meta.json` file doesn't exist, we will generate the sidebar config from the directory structure.
-    const subItems = await fs.readdir(workDir);
+
+    const includedFiles = globby.sync('*', {
+      cwd: workDir,
+      onlyFiles: false,
+      expandDirectories: false,
+      ignore: excludedFiles ?? [],
+    });
+
+    const subItems = [
+      ...new Set(includedFiles.map(file => file.split('/')[0])),
+    ];
+
     sideMeta = (
       await Promise.all(
         subItems.map(async item => {
@@ -114,6 +127,7 @@ export async function scanSideMeta(
           rootDir,
           docsDir,
           routePrefix,
+          excludedFiles,
         );
         const realPath = await detectFilePath(subDir);
         return {
@@ -152,6 +166,7 @@ export async function walk(
   workDir: string,
   routePrefix = '/',
   docsDir: string,
+  excludedFiles?: string[],
 ) {
   // find the `_meta.json` file
   const rootMetaFile = path.resolve(workDir, '_meta.json');
@@ -189,6 +204,7 @@ export async function walk(
       workDir,
       docsDir,
       routePrefix,
+      excludedFiles,
     );
   }
   return {