Refactor autogenerated sidebar groups

.changeset/slow-dragons-notice.md

@@ -0,0 +1,28 @@
+---
+'@astrojs/starlight': minor
+---
+
+**⚠️ BREAKING CHANGE:** This release changes how autogenerated links work in Starlight’s sidebar configuration.
+
+If you have sidebar groups using the `autogenerate` key, you must now wrap that configuration in an `items` array:
+
+```diff
+{
+    label: 'My group',
+-   autogenerate: { directory: 'some-dir' },
++   items: [{ autogenerate: { directory: 'some-dir' } }],
+}
+```
+
+This change unlocks the possibility to mix autogenerated links and other links in a single group, for example:
+
+```js
+{
+  label: 'Mixed group',
+  items: [
+    'example-page',
+    { autogenerate: { directory: 'examples' } },
+    { label: 'More examples', link: 'https://example.com' },
+  ],
+}
+```

docs/astro.config.mjs

@@ -131,7 +131,7 @@ export default defineConfig({
 						hi: 'गाइड',
 						uk: 'Ґайди',
 					},
-					autogenerate: { directory: 'guides' },
+					items: [{ autogenerate: { directory: 'guides' } }],
 				},
 				{
 					label: 'Components',
@@ -144,7 +144,7 @@ export default defineConfig({
 						'zh-CN': '组件',
 						uk: 'Компоненти',
 					},
-					autogenerate: { directory: 'components' },
+					items: [{ autogenerate: { directory: 'components' } }],
 				},
 				{
 					label: 'Reference',
@@ -163,7 +163,7 @@ export default defineConfig({
 						hi: 'संदर्भ',
 						uk: 'Довідник',
 					},
-					autogenerate: { directory: 'reference' },
+					items: [{ autogenerate: { directory: 'reference' } }],
 				},
 				{
 					label: 'Resources',
@@ -178,7 +178,7 @@ export default defineConfig({
 						ko: '리소스',
 						uk: 'Ресурси',
 					},
-					autogenerate: { directory: 'resources' },
+					items: [{ autogenerate: { directory: 'resources' } }],
 				},
 			],
 			expressiveCode: { shiki: { langs: [markdocGrammar] } },

docs/src/components/sidebar-preview.astro

@@ -1,6 +1,6 @@
 ---
 import type {
-	AutoSidebarGroup,
+	AutoSidebarEntries,
 	SidebarItem,
 	InternalSidebarLinkItem,
 } from '../../../packages/starlight/schemas/sidebar';
@@ -12,7 +12,7 @@ interface Props {
 	config: SidebarConfig;
 }
 
-type SidebarConfig = (Exclude<SidebarItem, AutoSidebarGroup | InternalSidebarLinkItem> & {
+type SidebarConfig = (Exclude<SidebarItem, AutoSidebarEntries | InternalSidebarLinkItem> & {
 	badge?: Badge;
 })[];
 

docs/src/content/docs/guides/sidebar.mdx

@@ -45,7 +45,7 @@ The following sidebar will be automatically generated:
 	]}
 />
 
-Learn more about autogenerated sidebars in the [autogenerated groups](#autogenerated-groups) section.
+Learn more about autogenerated sidebars in the [autogenerated links](#autogenerated-links) section.
 
 ## Add links and link groups
 
@@ -186,22 +186,24 @@ The configuration above generates the following sidebar:
 	]}
 />
 
-### Autogenerated groups
+### Autogenerated links
 
-Starlight can automatically generate a group in your sidebar based on a directory of your docs.
+Starlight can automatically generate links in your sidebar based on a directory of your docs.
 This is helpful when you do not want to manually enter each sidebar item in a group.
 
 By default, pages are sorted in alphabetical order according to the file [`id`](/reference/route-data/#id).
 
-Add an autogenerated group using an object with `label` and `autogenerate` properties. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration:
+Add autogenerated links using an object with the `autogenerate` property.
+Your `autogenerate` configuration must specify the `directory` to use for sidebar entries.
+For example, with the following configuration:
 
 ```js "label:" "autogenerate:"
 starlight({
 	sidebar: [
 		{
 			label: 'Constellations',
-			// Autogenerate a group of links for the 'constellations' directory.
-			autogenerate: { directory: 'constellations' },
+			// Autogenerate links for the 'constellations' directory.
+			items: [{ autogenerate: { directory: 'constellations' } }],
 		},
 	],
 });
@@ -262,7 +264,7 @@ sidebar:
 ---
 ```
 
-An autogenerated group including a page with the frontmatter above will generate the following sidebar:
+A group with autogenerated links including a page with the frontmatter above will generate the following sidebar:
 
 <SidebarPreview
 	config={[
@@ -282,12 +284,12 @@ An autogenerated group including a page with the frontmatter above will generate
 />
 
 :::note
-The `sidebar` frontmatter configuration is only used for links in autogenerated groups and docs links defined with the `slug` property. It does not apply to links defined with the `link` property.
+The `sidebar` frontmatter configuration is only used for autogenerated links and docs links defined with the `slug` property. It does not apply to links defined with the `link` property.
 :::
 
 ## Badges
 
-Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label.
+Links and groups can also include a `badge` property to display a badge next to their label.
 
 ```js {9,16}
 starlight({
@@ -302,11 +304,11 @@ starlight({
 				},
 			],
 		},
-		// An autogenerated group with an "Outdated" badge.
+		// A group with an "Outdated" badge.
 		{
 			label: 'Moons',
 			badge: 'Outdated',
-			autogenerate: { directory: 'moons' },
+			items: [{ autogenerate: { directory: 'moons' } }],
 		},
 	],
 });
@@ -438,20 +440,19 @@ The configuration above generates the following sidebar:
 
 ### Custom HTML attributes for autogenerated links
 
-Customize HTML attributes of all links in [autogenerated groups](#autogenerated-groups) by defining the `attrs` property in the `autogenerate` configuration.
+Customize HTML attributes of all [autogenerated links](#autogenerated-links) by defining the `attrs` property in the `autogenerate` configuration.
 Individual pages can specify custom attributes using the [`sidebar.attrs` frontmatter field](/reference/frontmatter/#attrs) which will be merged with the `autogenerate.attrs` configuration.
 
 For example, with the following configuration:
 
-```js {9}
+```js {8}
 starlight({
 	sidebar: [
 		{
-			label: 'Constellations',
 			autogenerate: {
-				// Autogenerate a group of links for the 'constellations' directory.
+				// Autogenerate links for the 'constellations' directory.
 				directory: 'constellations',
-				// Italicize all link labels in this group.
+				// Italicize all autogenerated link labels.
 				attrs: { style: 'font-style: italic' },
 			},
 		},
@@ -478,25 +479,16 @@ The following sidebar will be generated with all autogenerated links italicized:
 
 <SidebarPreview
 	config={[
+		{ label: 'Carina', link: '', attrs: { style: 'font-style: italic' } },
+		{ label: 'Centaurus', link: '', attrs: { style: 'font-style: italic' } },
 		{
-			label: 'Constellations',
+			label: 'seasonal',
 			items: [
-				{ label: 'Carina', link: '', attrs: { style: 'font-style: italic' } },
 				{
-					label: 'Centaurus',
+					label: 'Andromeda',
 					link: '',
 					attrs: { style: 'font-style: italic' },
 				},
-				{
-					label: 'seasonal',
-					items: [
-						{
-							label: 'Andromeda',
-							link: '',
-							attrs: { style: 'font-style: italic' },
-						},
-					],
-				},
 			],
 		},
 	]}
@@ -666,7 +658,7 @@ The configuration above generates the following sidebar:
 	]}
 />
 
-[Autogenerated groups](#autogenerated-groups) respect the `collapsed` value of their parent group:
+[Autogenerated links](#autogenerated-links) respect the `collapsed` value of their parent group:
 
 ```js {5-6}
 starlight({
@@ -675,7 +667,7 @@ starlight({
 			label: 'Constellations',
 			// Collapse the group and its autogenerated subgroups by default.
 			collapsed: true,
-			autogenerate: { directory: 'constellations' },
+			items: [{ autogenerate: { directory: 'constellations' } }],
 		},
 	],
 });
@@ -711,7 +703,9 @@ starlight({
 			// Do not collapse the "Constellations" group but collapse its
 			// autogenerated subgroups.
 			collapsed: false,
-			autogenerate: { directory: 'constellations', collapsed: true },
+			items: [
+				{ autogenerate: { directory: 'constellations', collapsed: true } },
+			],
 		},
 	],
 });

docs/src/content/docs/reference/frontmatter.md

@@ -284,7 +284,7 @@ draft: true
 ```
 
 Because draft pages are not included in build output, you cannot add draft pages directly to your site sidebar config using [slugs](/guides/sidebar/#internal-links).
-Draft pages in directories used for [autogenerated sidebar groups](/guides/sidebar/#autogenerated-groups) are automatically excluded in production builds.
+Draft pages in directories used for [autogenerated sidebar links](/guides/sidebar/#autogenerated-links) are automatically excluded in production builds.
 
 ### `sidebar`
 

examples/basics/astro.config.mjs

@@ -18,7 +18,7 @@ export default defineConfig({
 				},
 				{
 					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					items: [{ autogenerate: { directory: 'reference' } }],
 				},
 			],
 		}),

examples/markdoc/astro.config.mjs

@@ -20,7 +20,7 @@ export default defineConfig({
 				},
 				{
 					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					items: [{ autogenerate: { directory: 'reference' } }],
 				},
 			],
 		}),

examples/tailwind/astro.config.mjs

@@ -19,7 +19,7 @@ export default defineConfig({
 				},
 				{
 					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					items: [{ autogenerate: { directory: 'reference' } }],
 				},
 			],
 			customCss: ['./src/styles/global.css'],

packages/starlight/__tests__/basics/config-errors.test.ts

@@ -196,11 +196,11 @@ test('errors with bad nested sidebar config', () => {
 		parseStarlightConfigWithFriendlyErrors({
 			title: 'Test',
 			sidebar: [
+				// @ts-expect-error - Testing invalid config
 				{
 					label: 'Example',
 					items: [
 						{ label: 'Nested Example 1', link: '/' },
-						// @ts-expect-error - Testing invalid config
 						{ label: 'Nested Example 2', link: true },
 					],
 				},
@@ -238,7 +238,14 @@ test('errors with sidebar entry that includes `link` and `autogenerate`', () =>
 	expect(() =>
 		parseStarlightConfigWithFriendlyErrors({
 			title: 'Test',
-			sidebar: [{ label: 'Parent', link: '/parent', autogenerate: { directory: 'test' } }],
+			sidebar: [
+				{
+					label: 'Parent',
+					link: '/parent',
+					// @ts-expect-error - Testing invalid config
+					autogenerate: { directory: 'test' },
+				},
+			],
 		})
 	).toThrowErrorMatchingInlineSnapshot(`
 		"[AstroUserError]:
@@ -258,6 +265,7 @@ test('errors with sidebar entry that includes `items` and `autogenerate`', () =>
 				{
 					label: 'Parent',
 					items: [{ label: 'Child', link: '/parent/child' }],
+					// @ts-expect-error - Testing invalid config
 					autogenerate: { directory: 'test' },
 				},
 			],
@@ -318,3 +326,55 @@ test('errors if an invalid customCss file path is provided', () => {
 			You should move these CSS files into the \`src/\` directory and update the path in \`customCss\` to match."
 	`);
 });
+
+test('errors on removed autogenerated sidebar groups with no attributes', () => {
+	expect(() =>
+		parseStarlightConfigWithFriendlyErrors({
+			title: 'Test',
+			sidebar: [
+				{
+					label: 'Example',
+					// @ts-expect-error - Testing invalid config
+					autogenerate: { directory: 'test', collapsed: true },
+				},
+			],
+		})
+	).toThrowErrorMatchingInlineSnapshot(`
+		"[AstroUserError]:
+			Invalid config passed to starlight integration
+		Hint:
+			Found an \`autogenerate\` object with a \`label\`. Support for autogenerated sidebar groups was removed in Starlight v0.38.0.
+			You should instead create a group with the desired \`label\` and an \`items\` array containing the autogenerate config:
+
+			{
+			  label: 'Example',
+			  items: [{ autogenerate: { "directory": "test", "collapsed": true } }]
+			}"
+	`);
+});
+
+test('errors on removed autogenerated sidebar groups with attributes', () => {
+	expect(() =>
+		parseStarlightConfigWithFriendlyErrors({
+			title: 'Test',
+			sidebar: [
+				{
+					label: 'Example',
+					// @ts-expect-error - Testing invalid config
+					autogenerate: { directory: 'test', attrs: { 'data-test': 'test' } },
+				},
+			],
+		})
+	).toThrowErrorMatchingInlineSnapshot(`
+		"[AstroUserError]:
+			Invalid config passed to starlight integration
+		Hint:
+			Found an \`autogenerate\` object with a \`label\`. Support for autogenerated sidebar groups was removed in Starlight v0.38.0.
+			You should instead create a group with the desired \`label\` and an \`items\` array containing the autogenerate config:
+
+			{
+			  label: 'Example',
+			  items: [{ autogenerate: { "directory": "test", "attrs": { "data-test": "test" } } }]
+			}"
+	`);
+});