Add frontmatter to hide page from sidebar autogeneration (#441)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

5 files changed, 100 insertions, 4 deletions

diff --git a/.changeset/quiet-rules-drum.md b/.changeset/quiet-rules-drum.md
new file mode 100644
index 00000000..4a0ce3da
--- /dev/null
+++ b/.changeset/quiet-rules-drum.md
@@ -0,0 +1,13 @@
+---
+'@astrojs/starlight': minor
+---
+
+Add support for hiding entries from an autogenerated sidebar:
+
+ ```md
+ ---
+ title: About this project
+ sidebar:
+   hidden: true
+ ---
+ ```
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index d45bbc76..2259e5ec 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -191,7 +191,7 @@ next: false
 
 ### `sidebar`
 
-**type:** `{ label?: string; order?: number }`
+**type:** `{ label?: string; order?: number; hidden?: boolean }`
 
 Control how this page is displayed in the [sidebar](/reference/configuration/#sidebar), when using an autogenerated link group.
 
@@ -224,3 +224,18 @@ sidebar:
   order: 1
 ---
 ```
+
+#### `hidden`
+
+**type:** `boolean`
+**default:** `false`
+
+Prevents this page from being included in an autogenerated sidebar group.
+
+```md
+---
+title: Page to hide from autogenerated sidebar
+sidebar:
+  hidden: true
+---
+```
diff --git a/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts b/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts
new file mode 100644
index 00000000..7f133941
--- /dev/null
+++ b/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, test, vi } from 'vitest';
+import { getSidebar } from '../../utils/navigation';
+
+vi.mock('astro:content', async () =>
+	(await import('../test-utils')).mockedAstroContent({
+		docs: [
+			['index.mdx', { title: 'Home Page' }],
+			['environmental-impact.md', { title: 'Eco-friendly docs' }],
+			['reference/configuration.md', { title: 'Config Reference' }],
+			['reference/frontmatter.md', { title: 'Frontmatter Reference', sidebar: { hidden: true } }],
+			['guides/components.mdx', { title: 'Components' }],
+		],
+	})
+);
+
+describe('getSidebar', () => {
+	test('excludes sidebar entries with hidden: true in frontmatter', () => {
+		expect(getSidebar('/', undefined)).toMatchInlineSnapshot(`
+    [
+      {
+        "href": "/",
+        "isCurrent": true,
+        "label": "Home",
+        "type": "link",
+      },
+      {
+        "collapsed": false,
+        "entries": [
+          {
+            "href": "/intro/",
+            "isCurrent": false,
+            "label": "Introduction",
+            "type": "link",
+          },
+          {
+            "href": "/next-steps/",
+            "isCurrent": false,
+            "label": "Next Steps",
+            "type": "link",
+          },
+        ],
+        "label": "Start Here",
+        "type": "group",
+      },
+      {
+        "collapsed": false,
+        "entries": [
+          {
+            "href": "/reference/configuration/",
+            "isCurrent": false,
+            "label": "Config Reference",
+            "type": "link",
+          },
+        ],
+        "label": "Reference",
+        "type": "group",
+      },
+    ]
+  `);
+	});
+});
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts
index b005f955..b45dcc3a 100644
--- a/packages/starlight/schema.ts
+++ b/packages/starlight/schema.ts
@@ -142,6 +142,11 @@ export function docsSchema() {
 					 * Defaults to the page `title` if not set.
 					 */
 					label: z.string().optional(),
+
+					/**
+					 * Prevents this page from being included in autogenerated sidebar groups.
+					 */
+					hidden: z.boolean().default(false),
 				})
 				.default({}),
 		});
diff --git a/packages/starlight/utils/navigation.ts b/packages/starlight/utils/navigation.ts
index 2b63ec96..816c5e79 100644
--- a/packages/starlight/utils/navigation.ts
+++ b/packages/starlight/utils/navigation.ts
@@ -83,9 +83,11 @@ function groupFromAutogenerateConfig(
 	const dirDocs = routes.filter(
 		(doc) =>
 			// Match against `foo.md` or `foo/index.md`.
-			stripExtension(doc.id) === localeDir ||
-			// Match against `foo/anything/else.md`.
-			doc.id.startsWith(localeDir + '/')
+			(stripExtension(doc.id) === localeDir ||
+				// Match against `foo/anything/else.md`.
+				doc.id.startsWith(localeDir + '/')) &&
+			// Remove any entries that should be hidden
+			!doc.entry.data.sidebar.hidden
 	);
 	const tree = treeify(dirDocs, localeDir);
 	return {