fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars and place `index.md` at the top by SoonIter · Pull Request #3171 · web-infra-dev/rspress

SoonIter · 2026-02-28T09:32:17Z

Summary

Related Issue

Checklist

Tests updated (or not required).
Documentation updated (or not required).

AI Summary

What

When route.exclude patterns are configured (e.g. ['_components/**']), excluded files no longer appear in auto-generated sidebar navigation.

Previously, route.exclude only filtered files from route generation (RouteService), but the sidebar auto-generation (fsDirToMetaItems() in normalize.ts) scanned directories independently with fs.readdir() and had no knowledge of these exclude patterns. This caused excluded files to still show up in the sidebar.

How

Reuses the existing RouteService.isExistRoute(link) method in the sidebar generation code. When generating a sidebar file item, after computing its route path (link), we check whether that route actually exists. If it doesn't (because the file was excluded by route.exclude), the sidebar item is skipped.

Key changes in packages/core/src/node/auto-nav-sidebar/normalize.ts:

metaFileItemToSidebarItem() — After computing link, checks RouteService.getInstance()?.isExistRoute(link). Returns null if the route doesn't exist.
metaItemToSidebarItem() — Return type extended with | null. Empty dir and dir-section-header groups are pruned when all children are excluded.
metaDirItemToSidebarItem() — getItems() filters out null results. Same-name file and index file callers handle null gracefully by falling back to non-clickable directory behavior.

What this covers

No-config sidebars: Files excluded by route.exclude are filtered out during filesystem scanning
_meta.json sidebars: Files explicitly listed in _meta.json but excluded by route.exclude are silently skipped
Empty group pruning: Directories where all children are excluded produce no sidebar entry (instead of an empty group)
Backward compatible: When RouteService has no isExistRoute method (e.g. in tests with partial mocks), no filtering occurs — existing behavior is preserved

Tests

route.exclude should filter sidebar items — no-config sidebar with isExistRoute mock excluding _components paths
_meta.json referencing excluded file should skip it — _meta.json explicitly references an excluded file, verifies it's silently skipped
Both tests also verify excluded files don't appear in mdFileSet

This PR was written using Vibe Kanban

cloudflare-workers-and-pages · 2026-02-28T09:33:54Z

Deploying rspress-v2 with Cloudflare Pages

Latest commit:	`2bad4c9`
Status:	✅ Deploy successful!
Preview URL:	https://9d03acfd.rspress-v2.pages.dev
Branch Preview URL:	https://syt-vibe-kanban-752f-3161-84.rspress-v2.pages.dev

View logs

github-actions · 2026-02-28T09:35:04Z

Rsdoctor Bundle Diff Analysis

Found 3 projects in monorepo, 1 project with changes.

📊 Quick Summary

Project	Total Size	Change
node	12.0 MB	0
web	15.9 MB	-1.5 KB (-0.0%)
node_md	1.5 MB	0

📋 Detailed Reports (Click to expand)

📁 web

Path: website/doc_build/diff-rsdoctor/web/rsdoctor-data.json

📌 Baseline Commit: 4d01488bf0 | PR: #3180

Metric	Current	Baseline	Change
📊 Total Size	15.9 MB	15.9 MB	-1.5 KB (-0.0%)
📄 JavaScript	15.7 MB	15.7 MB	-1.5 KB (-0.0%)
🎨 CSS	120.3 KB	120.3 KB	0
🌐 HTML	0 B	0 B	0
📁 Other Assets	163.6 KB	163.6 KB	0

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

Copilot

Pull request overview

Fixes issues where pages excluded by route.exclude / route.excludeConvention were still showing up in auto-generated (no-config) sidebars by filtering sidebar items against the actual route table (RouteService.isExistRoute).

Changes:

Filter file-based sidebar items when the corresponding route does not exist, and prune empty directory groups / section headers.
Add fixtures and tests to cover excluded-route filtering (both filesystem-discovered sidebars and _meta.json-driven sidebars).
Add an implementation plan document describing the approach.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/core/src/node/auto-nav-sidebar/normalize.ts	Filters sidebar items via `RouteService.isExistRoute`, handles `null` items, and prunes empty groups/headers.
packages/core/src/node/auto-nav-sidebar/walk.test.ts	Adds tests for `route.exclude` filtering and `_meta.json` references to excluded pages; stabilizes RouteService mock resetting.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-no-meta/api/_components/Button.mdx	New fixture to simulate an excluded page under an underscore directory.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/_nav.json	New fixture nav for excluded-meta test case.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/_meta.json	New fixture `_meta.json` that references an excluded file.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/a.md	New fixture page “a”.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/b.mdx	New fixture page “b”.
packages/core/src/node/auto-nav-sidebar/fixtures/docs-exclude-meta/guide/excluded-file.md	New fixture page intended to be excluded by route existence filtering.
docs/plans/2026-02-27-exclude-routes-from-sidebar.md	Added implementation plan documentation for this feature/change.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/core/src/node/auto-nav-sidebar/normalize.ts

docs/plans/2026-02-27-exclude-routes-from-sidebar.md

smileluck · 2026-03-02T10:31:13Z

https://github.com/smileluck/SmileX-Note-Repress/blob/main/plugins/auto-meta-plugin.ts

Does it work if I generate the _meta.json file automatically by monitoring the file list?

Plan to fix #3161 and #848 where excluded routes still appear in auto-generated sidebars. Approach: reuse RouteService.isExistRoute() to filter sidebar items during generation.

SoonIter · 2026-03-02T12:17:14Z

smileluck/SmileX-Note-Repress@main/plugins/auto-meta-plugin.ts

Does it work if I generate the _meta.json file automatically by monitoring the file list?

@smileluck Thanks for the suggestion 👍

From the perspective of _meta.json’s design goals, even if it is auto-generated based on the file list, it still typically requires manual intervention, for example:

Adjusting the order of sidebar items
Controlling grouping structure or title or divider

If we rely entirely on auto-generation, the result is essentially “directory structure + lexicographical order.” and no-config pattern has implemented it, it's a supplement to _meta.json (only some cases)

If the plugin you write meets your own needs, you can try using it yourself for some time, and then add it to Community plugins .

SoonIter · 2026-03-09T03:14:20Z

#2730

Copilot AI review requested due to automatic review settings February 28, 2026 09:32

Copilot started reviewing on behalf of SoonIter February 28, 2026 09:32 View session

SoonIter changed the title ~~3161 和 848, Excluded routes still appear in the no-config sidebars (vibe-kanban)~~ fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars Feb 28, 2026

github-actions bot added the change: fix label Feb 28, 2026

Copilot AI reviewed Feb 28, 2026

View reviewed changes

packages/core/src/node/auto-nav-sidebar/normalize.ts Show resolved Hide resolved

docs/plans/2026-02-27-exclude-routes-from-sidebar.md Outdated Show resolved Hide resolved

SoonIter added 3 commits March 2, 2026 19:42

docs: add implementation plan for route.exclude sidebar filtering

6793250

Plan to fix #3161 and #848 where excluded routes still appear in auto-generated sidebars. Approach: reuse RouteService.isExistRoute() to filter sidebar items during generation.

chore: update

4d8ff82

chore: remove implementation plan document

ef084ce

chore: update

f7193a8

SoonIter force-pushed the syt-vibe-kanban/752f-3161-848-exclude branch from 7228ddf to f7193a8 Compare March 2, 2026 12:49

chore: update

2bad4c9

SoonIter changed the title ~~fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars~~ fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars and place index.md at the top Mar 2, 2026

SoonIter enabled auto-merge (squash) March 2, 2026 13:13

SoonIter requested a review from Timeless0911 March 2, 2026 13:14

Timeless0911 approved these changes Mar 2, 2026

View reviewed changes

SoonIter merged commit e64a878 into main Mar 2, 2026
6 of 7 checks passed

SoonIter deleted the syt-vibe-kanban/752f-3161-848-exclude branch March 2, 2026 13:27

SoonIter mentioned this pull request Mar 9, 2026

chore: fix the route.excludes should affect auto-nav-sidebar #2730

Closed

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

fix(auto-nav-sidebar): exclude route.exclude files from auto-generated sidebars and place `index.md` at the top#3171
SoonIter merged 5 commits intomainfrom
syt-vibe-kanban/752f-3161-848-exclude

SoonIter commented Feb 28, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Feb 28, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 28, 2026 •

edited

Loading

📁 web

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

smileluck commented Mar 2, 2026

Uh oh!

SoonIter commented Mar 2, 2026

Uh oh!

Uh oh!

SoonIter commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

SoonIter commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Checklist

AI Summary

What

How

What this covers

Tests

Uh oh!

cloudflare-workers-and-pages bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying rspress-v2 with Cloudflare Pages

Uh oh!

github-actions bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rsdoctor Bundle Diff Analysis

📁 web

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

smileluck commented Mar 2, 2026

Uh oh!

SoonIter commented Mar 2, 2026

Uh oh!

Uh oh!

SoonIter commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SoonIter commented Feb 28, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 28, 2026 •

edited

Loading

github-actions bot commented Feb 28, 2026 •

edited

Loading