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

Co-authored-by: HiDeoo <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

.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
+ ---
+ ```

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
+---
+```

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",
+      },
+    ]
+  `);
+	});
+});

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({}),
 		});

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 {