@astrojs/starlight 0.38.4 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @astrojs/starlight
 
+## 0.39.0
+
+### Minor Changes
+
+- [#3618](https://github.com/withastro/starlight/pull/3618) [`dcf6d09`](https://github.com/withastro/starlight/commit/dcf6d094bbcfa1f83e45742901f4178df07c2156) Thanks [@HiDeoo](https://github.com/HiDeoo)! - **⚠️ 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' },
+    ],
+  }
+  ```
+
+  This release also updates the shape of autogenerated sidebar entries in route data. Autogenerated links and groups in `Astro.locals.starlightRoute.sidebar` now include an `autogenerate` object with the [configured `directory` value](https://starlight.astro.build/guides/sidebar/#autogenerated-groups):
+
+  ```js
+  {
+    type: 'link',
+    label: 'Example',
+    href: '/examples/example/',
+    isCurrent: false,
+    autogenerate: { directory: 'examples' }
+  }
+  ```
+
+- [#3618](https://github.com/withastro/starlight/pull/3618) [`dcf6d09`](https://github.com/withastro/starlight/commit/dcf6d094bbcfa1f83e45742901f4178df07c2156) Thanks [@HiDeoo](https://github.com/HiDeoo)! - **⚠️ BREAKING CHANGE:** This release changes the default collapsed state of autogenerated sidebar subgroups.
+
+  Autogenerated subgroups no longer inherit the `collapsed` value from their parent group. They are now expanded by default unless explicitly configured with [`autogenerate.collapsed`](https://starlight.astro.build/reference/configuration/#collapsing-groups).
+
+  If your sidebar configuration relies on a collapsed parent group to also collapse its autogenerated subgroups, update your configuration to set `autogenerate.collapsed` to `true`:
+
+  ```diff
+  {
+    label: 'Reference',
+    collapsed: true,
+    items: [
+  -   { autogenerate: { directory: 'reference' } },
+  +   { autogenerate: { directory: 'reference', collapsed: true } },
+    ],
+  }
+  ```
+
+- [#3845](https://github.com/withastro/starlight/pull/3845) [`4d755f5`](https://github.com/withastro/starlight/commit/4d755f591bbca682d01a70162a10c12ab5187c61) Thanks [@delucis](https://github.com/delucis)! - Adds a `<link rel="alternate" hreflang="x-default" href="...">` tag pointing to the default locale in multilingual sites. The `x-default` alternate is used as a signal of which language to fall back to if no other is available. Learn more in Google’s [SEO localization docs](https://developers.google.com/search/docs/specialty/international/localized-versions#xdefault).
+
+- [#3862](https://github.com/withastro/starlight/pull/3862) [`ec70630`](https://github.com/withastro/starlight/commit/ec70630cbbe43bb5b026ddabfe7224759c798a4b) Thanks [@itrew](https://github.com/itrew)! - Makes spacing of items in nested lists more consistent
+
+- [#3872](https://github.com/withastro/starlight/pull/3872) [`417a66c`](https://github.com/withastro/starlight/commit/417a66c4acf3a7408fc0cea701aa5f143c540e5c) Thanks [@tats-u](https://github.com/tats-u)! - Enables [the CSS property `text-autospace`](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/text-autospace) in Chinese and Japanese documents.
+
+  If you would prefer to disable autospacing in Chinese and Japanese pages, you can add the following custom CSS to your site:
+
+  ```css
+  [lang]:where(:lang(zh, ja)) {
+    text-autospace: initial;
+  }
+  ```
+
+- [#3797](https://github.com/withastro/starlight/pull/3797) [`9764ebd`](https://github.com/withastro/starlight/commit/9764ebdab8d12983064d11515b6d92355a4d95eb) Thanks [@delucis](https://github.com/delucis)! - Avoids the risk of layout shift when users expand and collapse sidebar groups
+
+  This release can introduce additional padding to the site sidebar on certain devices to reserve space for scrollbars. You may wish to inspect your site sidebar visually when upgrading.
+
+  If you would prefer to keep the previous styling, you can add the following custom CSS to your site:
+
+  ```css
+  .sidebar-pane {
+    scrollbar-gutter: auto;
+  }
+  ```
+
+- [#3858](https://github.com/withastro/starlight/pull/3858) [`6672c35`](https://github.com/withastro/starlight/commit/6672c35b914cd53f1641a43a7ea8e7ef08d9cc8f) Thanks [@delucis](https://github.com/delucis)! - Updates `i18next`, used for Starlight’s localization APIs, from v23 to v26
+
+  There should not be any user-facing changes from this update
+
+## 0.38.5
+
+### Patch Changes
+
+- [#3854](https://github.com/withastro/starlight/pull/3854) [`ccf6000`](https://github.com/withastro/starlight/commit/ccf6000549c580796a8a8730637074c25e3ccc44), [#3877](https://github.com/withastro/starlight/pull/3877) [`47451bc`](https://github.com/withastro/starlight/commit/47451bc56d84ed19bee73e3d4dbb58d28951ef38) Thanks [@delucis](https://github.com/delucis)! - Updates internal dependencies
+
 ## 0.38.4
 
 ### Patch Changes

package/components/PageFrame.astro

@@ -56,6 +56,7 @@ const { hasSidebar } = Astro.locals.starlightRoute;
 			width: 100%;
 			background-color: var(--sl-color-black);
 			overflow-y: auto;
+			scrollbar-gutter: stable;
 		}
 
 		:global([aria-expanded='true']) ~ .sidebar-pane {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.38.4",
+  "version": "0.39.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -45,42 +45,42 @@
     "astro": "^6.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.57.0",
-    "@types/node": "^22.19.3",
-    "@vitest/coverage-v8": "^4.1.0",
-    "astro": "^6.0.1",
-    "linkedom": "^0.18.4",
-    "vitest": "^4.1.0"
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^22.19.17",
+    "@vitest/coverage-v8": "^4.1.5",
+    "astro": "^6.2.2",
+    "linkedom": "^0.18.12",
+    "vitest": "^4.1.5"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.0.0",
-    "@astrojs/mdx": "^5.0.0",
-    "@astrojs/sitemap": "^3.7.1",
+    "@astrojs/markdown-remark": "^7.1.1",
+    "@astrojs/mdx": "^5.0.4",
+    "@astrojs/sitemap": "^3.7.2",
     "@pagefind/default-ui": "^1.3.0",
     "@types/hast": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
-    "astro-expressive-code": "^0.41.6",
+    "astro-expressive-code": "^0.42.0",
     "bcp-47": "^2.1.0",
-    "hast-util-from-html": "^2.0.1",
-    "hast-util-select": "^6.0.2",
-    "hast-util-to-string": "^3.0.0",
-    "hastscript": "^9.0.0",
-    "i18next": "^23.11.5",
-    "js-yaml": "^4.1.0",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-select": "^6.0.4",
+    "hast-util-to-string": "^3.0.1",
+    "hastscript": "^9.0.1",
+    "i18next": "^26.0.7",
+    "js-yaml": "^4.1.1",
     "klona": "^2.0.6",
-    "magic-string": "^0.30.17",
-    "mdast-util-directive": "^3.0.0",
-    "mdast-util-to-markdown": "^2.1.0",
+    "magic-string": "^0.30.21",
+    "mdast-util-directive": "^3.1.0",
+    "mdast-util-to-markdown": "^2.1.2",
     "mdast-util-to-string": "^4.0.0",
     "pagefind": "^1.3.0",
-    "rehype": "^13.0.1",
-    "rehype-format": "^5.0.0",
-    "remark-directive": "^3.0.0",
+    "rehype": "^13.0.2",
+    "rehype-format": "^5.0.1",
+    "remark-directive": "^4.0.0",
     "ultrahtml": "^1.6.0",
     "unified": "^11.0.5",
-    "unist-util-visit": "^5.0.0",
-    "vfile": "^6.0.2"
+    "unist-util-visit": "^5.1.0",
+    "vfile": "^6.0.3"
   },
   "publishConfig": {
     "provenance": true

package/schemas/sidebar.ts

@@ -50,31 +50,63 @@ const SidebarLinkItemSchema = z.strictObject({
 });
 export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
 
-const AutoSidebarGroupSchema = z.strictObject({
-	...SidebarGroupSchema.shape,
-	/** Enable autogenerating a sidebar category from a specific docs directory. */
-	autogenerate: z.object({
-		/** The directory to generate sidebar items for. */
-		directory: z.string().transform(stripLeadingAndTrailingSlashes),
+const AutoSidebarEntriesSchema = z
+	.object({
 		/**
-		 * Whether the autogenerated subgroups should be collapsed by default.
-		 * Defaults to the `AutoSidebarGroup` `collapsed` value.
+		 * Explicitly prevent autogenerated groups which are no longer supported as the final type for
+		 * supported sidebar item is a non-discriminated union where TypeScript will not perform excess
+		 * property checks. This means that a user could define a sidebar group with an autogenerated
+		 * property, not getting a TypeScript error, and only have it fail at runtime.
+		 * @see https://github.com/microsoft/TypeScript/issues/20863
 		 */
-		collapsed: z.boolean().optional(),
-		/** HTML attributes to add to the autogenerated link items. */
-		attrs: SidebarLinkItemHTMLAttributesSchema(),
-		// TODO: not supported by Docusaurus but would be good to have
-		/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
-		// depth: z.number().optional(),
-	}),
-});
-export type AutoSidebarGroup = z.infer<typeof AutoSidebarGroupSchema>;
+		label: z.custom<never>().optional(),
+		/** Enable autogenerating entries from a specific docs directory. */
+		autogenerate: z.object({
+			/** The directory to generate sidebar items for. */
+			directory: z.string().transform(stripLeadingAndTrailingSlashes),
+			/** Whether the autogenerated subgroups should be collapsed by default. Default: `false`. */
+			collapsed: z.boolean().optional(),
+			/** HTML attributes to add to the autogenerated link items. */
+			attrs: SidebarLinkItemHTMLAttributesSchema(),
+			// TODO: not supported by Docusaurus but would be good to have
+			/** How many directories deep to include from this directory in the sidebar. Default: `Infinity`. */
+			// depth: z.number().optional(),
+		}),
+	})
+	.strict()
+	.superRefine((config, ctx) => {
+		if (!('label' in config)) return;
+
+		// TODO: Remove this error message in a future release once most users have migrated
+		ctx.addIssue({
+			code: 'custom',
+			message:
+				`Found an \`autogenerate\` object with a \`label\`. Support for autogenerated sidebar groups was removed in Starlight v0.38.0.\n` +
+				`You should instead create a group with the desired \`label\` and an \`items\` array containing the autogenerate config:\n\n` +
+				`{\n` +
+				`  label: '${config.label}',\n` +
+				`  items: [{ autogenerate: ${JSON.stringify(
+					config.autogenerate,
+					// Hide empty attrs object that is automatically added by the schema default value.
+					(key, value: unknown) =>
+						key === 'attrs' &&
+						typeof value === 'object' &&
+						value !== null &&
+						Object.keys(value).length === 0
+							? undefined
+							: value,
+					' '
+				).replace(/\n\s*/g, ' ')} }]\n` +
+				`}`,
+		});
+	});
+export type AutoSidebarEntries = z.infer<typeof AutoSidebarEntriesSchema>;
 
 type ManualSidebarGroupInput = z.input<typeof SidebarGroupSchema> & {
 	/** Array of links and subcategories to display in this category. */
 	items: Array<
 		| z.input<typeof SidebarLinkItemSchema>
-		| z.input<typeof AutoSidebarGroupSchema>
+		| z.input<typeof AutoSidebarEntriesSchema>
 		| z.input<typeof InternalSidebarLinkItemSchema>
 		| z.input<typeof InternalSidebarLinkItemShorthandSchema>
 		| ManualSidebarGroupInput
@@ -85,7 +117,7 @@ type ManualSidebarGroupOutput = z.output<typeof SidebarGroupSchema> & {
 	/** Array of links and subcategories to display in this category. */
 	items: Array<
 		| z.output<typeof SidebarLinkItemSchema>
-		| z.output<typeof AutoSidebarGroupSchema>
+		| z.output<typeof AutoSidebarEntriesSchema>
 		| z.output<typeof InternalSidebarLinkItemSchema>
 		| z.output<typeof InternalSidebarLinkItemShorthandSchema>
 		| ManualSidebarGroupOutput
@@ -101,7 +133,7 @@ const ManualSidebarGroupSchema: z.ZodType<ManualSidebarGroupOutput, ManualSideba
 				.union([
 					SidebarLinkItemSchema,
 					ManualSidebarGroupSchema,
-					AutoSidebarGroupSchema,
+					AutoSidebarEntriesSchema,
 					InternalSidebarLinkItemSchema,
 					InternalSidebarLinkItemShorthandSchema,
 				])
@@ -124,7 +156,7 @@ export type InternalSidebarLinkItem = z.output<typeof InternalSidebarLinkItemSch
 export const SidebarItemSchema = z.union([
 	SidebarLinkItemSchema,
 	ManualSidebarGroupSchema,
-	AutoSidebarGroupSchema,
+	AutoSidebarEntriesSchema,
 	InternalSidebarLinkItemSchema,
 	InternalSidebarLinkItemShorthandSchema,
 ]);

package/style/markdown.css

@@ -31,31 +31,31 @@
 		overflow-wrap: anywhere;
 	}
 
+	/*
+	 * This complex selector manages spacing inside lists.
+	 *
+	 * - Finds all lists containing items with non-inline direct children (e.g.
+	 *   ul > li > p)
+	 * - Applies a bottom margin to the last non-inline child of each list item
+	 *   in this list
+	 *
+	 * This ensures that even if only one list item contains a block element
+	 * (most commonly a paragraph), siblings of that list item are spaced
+	 * consistently.
+	 */
 	.sl-markdown-content
-	li
-	> :is(
-		:last-child:not(
-				li,
-				ul,
-				ol,
-				a,
-				strong,
-				em,
-				del,
-				span,
-				input,
-				code,
-				br,
-				script,
-				:where(.not-content *)
-			),
-			/**
-			 * For list items ending with 1 or multiple script elements (`:has(~ script:last-child)`), we
-			 * need to style the last non-script element (`:not(script)`) that doesn't have a subsequent
-			 * sibling that is not a script (`:not(:has(~ :not(script)))`).
+	 :is(ol, ul):has(> li > :not(a, strong, em, del, span, input, code, br, script, ol, ul))
+	 > li
+	 > :is(
+			:last-child:not(a, strong, em, del, span, input, code, br, script, :where(.not-content *)),
+			/*
+			 * For list items ending with 1 or multiple script elements (`:has(~
+			 * script:last-child)`), we need to style the last non-script
+			 * element (`:not(script)`) that doesn't have a subsequent sibling
+			 * that is not a script (`:not(:has(~ :not(script)))`).
 			 */
-		:not(script):has(~ script:last-child):not(:has(~ :not(script)))
-	) {
+			:not(script):has(~ script:last-child):not(:has(~ :not(script)))
+	 ) {
 		margin-bottom: 1.25rem;
 	}
 

package/style/reset.css

@@ -28,6 +28,21 @@
 		background-color: var(--sl-color-bg);
 	}
 
+	[lang]:where(:lang(zh, ja)) {
+		text-autospace: normal;
+	}
+
+	[lang]:where(:not(:lang(zh, ja))) {
+		text-autospace: initial;
+	}
+
+	pre,
+	code,
+	samp,
+	kbd {
+		text-autospace: no-autospace;
+	}
+
 	input,
 	button,
 	textarea,

package/utils/createTranslationSystem.ts

@@ -72,7 +72,11 @@ export async function createTranslationSystem<T extends i18nSchemaOutput>(
 
 		const t = i18n.getFixedT(lang, I18nextNamespace) as I18nT;
 		t.all = () => i18n.getResourceBundle(lang, I18nextNamespace) as ReturnType<I18nT['all']>;
-		t.exists = (key, options) => i18n.exists(key, { lng: lang, ns: I18nextNamespace, ...options });
+		// Since i18next 25.10.4 the `ExistsFunction` type has a signature including a predicate that
+		// TS cannot preserve when composing a new function to add default options.
+		// See: https://github.com/i18next/i18next/issues/2425
+		t.exists = ((key, options) =>
+			i18n.exists(key, { lng: lang, ns: I18nextNamespace, ...options })) as ExistsFunction;
 		t.dir = (dirLang = lang) => i18n.dir(dirLang);
 
 		return t;

package/utils/error-map.ts

@@ -107,6 +107,12 @@ const errorMap: z.core.$ZodErrorMap = (issue) => {
 			for (const unionError of issue.errors) {
 				const expectedShape: string[] = [];
 				for (const issue of unionError) {
+					// We sometimes use `z.NEVER` to explicitly error on certain property combinations in
+					// non-discriminated unions to make it easier for users to identify invalid config, e.g.
+					// autogenerated groups in the sidebar no longer being supported. Having these properties
+					// show up in the error message with an expected type of `never` is noisy and not helpful
+					// so we skip them here.
+					if (issue.code === 'invalid_type' && issue.expected === 'never') continue;
 					// If the issue is a nested union error, show the associated error message instead of the
 					// base error message.
 					if (issue.code === 'invalid_union') {

package/utils/head.ts

@@ -91,6 +91,14 @@ export function getHead(
 				},
 			});
 		}
+		headDefaults.push({
+			tag: 'link',
+			attrs: {
+				rel: 'alternate',
+				hreflang: 'x-default',
+				href: localizedUrl(canonical, config.defaultLocale.locale, project.trailingSlash).href,
+			},
+		});
 	}
 
 	// Link to sitemap, but only when `site` is set.

package/utils/i18n.ts

@@ -187,8 +187,9 @@ function getLocaleDir(locale: Intl.Locale): 'ltr' | 'rtl' {
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-return
 		return locale.textInfo.direction;
 	} else if ('getTextInfo' in locale) {
-		// @ts-expect-error - `getTextInfo` is not typed but is available in some non-v8 based environments.
-		// eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access
+		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+		// @ts-ignore - `getTextInfo` is not typed in older versions of TypeScript but is available in some browsers and newer versions of Node.
+		// TODO: remove or switch to @ts-expect-error in #3572
 		return locale.getTextInfo().direction;
 	}
 	// Firefox does not support `textInfo` or `getTextInfo` yet so we fallback to a well-known list
@@ -196,7 +197,7 @@ function getLocaleDir(locale: Intl.Locale): 'ltr' | 'rtl' {
 	// eslint-disable-next-line @typescript-eslint/ban-ts-comment
 	// @ts-ignore — This is a type error with newer versions of TypeScript’s DOM types.
 	// TODO: remove or switch to @ts-expect-error in #3572
-	return wellKnownRTL.includes(locale.language) ? 'rtl' : 'ltr';
+	return wellKnownRTL.includes((locale as Intl.Locale).language) ? 'rtl' : 'ltr';
 }
 
 /**

package/utils/navigation.ts

@@ -4,7 +4,7 @@ import config from 'virtual:starlight/user-config';
 import type { Badge, I18nBadge, I18nBadgeConfig } from '../schemas/badge';
 import type { PrevNextLinkConfig } from '../schemas/prevNextLink';
 import type {
-	AutoSidebarGroup,
+	AutoSidebarEntries,
 	InternalSidebarLinkItem,
 	LinkHTMLAttributes,
 	SidebarItem,
@@ -24,9 +24,13 @@ import { getLocaleRoutes, routes } from './routing';
 import type {
 	SidebarGroup,
 	SidebarLink,
+	SidebarManualLink,
 	PaginationLinks,
 	Route,
 	SidebarEntry,
+	SidebarAutoLink,
+	SidebarAutoGroup,
+	SidebarAutogenerateRouteData,
 } from './routing/types';
 import { localeToLang, localizedFilePath, slugToPathname } from './slugs';
 import { isAbsoluteUrl } from './url';
@@ -35,6 +39,8 @@ import type { StarlightConfig } from './user-config';
 const DirKey = Symbol('DirKey');
 const SlugKey = Symbol('SlugKey');
 
+const rootAutogenerate: SidebarAutogenerateRouteData = { directory: '' };
+
 const neverPathFormatter = createPathFormatter({ trailingSlash: 'never' });
 
 const docsCollectionPathFromRoot = getCollectionPathFromRoot('docs', project);
@@ -68,14 +74,13 @@ function isDir(data: Record<string, unknown>): data is Dir {
 /** Convert an item in a user’s sidebar config to a sidebar entry. */
 function configItemToEntry(
 	item: SidebarItem,
-	currentPathname: string,
 	locale: string | undefined,
 	routes: Route[]
-): SidebarEntry {
+): SidebarEntry | SidebarEntry[] {
 	if ('link' in item) {
 		return linkFromSidebarLinkItem(item, locale);
 	} else if ('autogenerate' in item) {
-		return groupFromAutogenerateConfig(item, locale, routes, currentPathname);
+		return entriesFromAutogenerateConfig(item, locale, routes);
 	} else if ('slug' in item) {
 		return linkFromInternalSidebarLinkItem(item, locale);
 	} else {
@@ -83,22 +88,22 @@ function configItemToEntry(
 		return {
 			type: 'group',
 			label,
-			entries: item.items.map((i) => configItemToEntry(i, currentPathname, locale, routes)),
+			entries: item.items.flatMap((i) => configItemToEntry(i, locale, routes)),
 			collapsed: item.collapsed,
 			badge: getSidebarBadge(item.badge, locale, label),
 		};
 	}
 }
 
-/** Autogenerate a group of links from a user’s sidebar config. */
-function groupFromAutogenerateConfig(
-	item: AutoSidebarGroup,
+/** Autogenerate links and groups from a user’s sidebar config. */
+function entriesFromAutogenerateConfig(
+	item: AutoSidebarEntries,
 	locale: string | undefined,
-	routes: Route[],
-	currentPathname: string
-): SidebarGroup {
-	const { attrs, collapsed: subgroupCollapsed, directory } = item.autogenerate;
+	routes: Route[]
+): (SidebarAutoLink | SidebarGroup)[] {
+	const { attrs, collapsed, directory } = item.autogenerate;
 	const localeDir = locale ? locale + '/' + directory : directory;
+	const autogenerate = { directory };
 	const dirDocs = routes.filter((doc) => {
 		const filePathFromContentDir = getRoutePathRelativeToCollectionRoot(doc, locale);
 		return (
@@ -109,20 +114,7 @@ function groupFromAutogenerateConfig(
 		);
 	});
 	const tree = treeify(dirDocs, locale, localeDir);
-	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return {
-		type: 'group',
-		label,
-		entries: sidebarFromDir(
-			tree,
-			currentPathname,
-			locale,
-			subgroupCollapsed ?? item.collapsed,
-			attrs
-		),
-		collapsed: item.collapsed,
-		badge: getSidebarBadge(item.badge, locale, label),
-	};
+	return sidebarFromDir(tree, { collapsed: collapsed ?? false, attrs }, autogenerate);
 }
 
 /** Create a link entry from a manual link item in user config. */
@@ -134,7 +126,12 @@ function linkFromSidebarLinkItem(item: SidebarLinkItem, locale: string | undefin
 		if (locale) href = '/' + locale + href;
 	}
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return makeSidebarLink(href, label, getSidebarBadge(item.badge, locale, label), item.attrs);
+	return makeSidebarLink({
+		href,
+		label,
+		badge: getSidebarBadge(item.badge, locale, label),
+		attrs: item.attrs,
+	});
 }
 
 /** Create a link entry from an automatic internal link item in user config. */
@@ -169,39 +166,44 @@ function linkFromInternalSidebarLinkItem(
 		frontmatter.title;
 	const badge = item.badge ?? frontmatter.sidebar?.badge;
 	const attrs = { ...frontmatter.sidebar?.attrs, ...item.attrs };
-	return makeSidebarLink(
-		slugToPathname(route.id),
+	return makeSidebarLink({
+		href: slugToPathname(route.id),
 		label,
-		getSidebarBadge(badge, locale, label),
-		attrs
-	);
+		badge: getSidebarBadge(badge, locale, label),
+		attrs,
+	});
+}
+
+interface MakeLinkOptions {
+	autogenerate?: SidebarAutogenerateRouteData | undefined;
+	href: string;
+	label: string;
+	badge?: Badge | undefined;
+	attrs?: LinkHTMLAttributes | undefined;
 }
 
 /** Process sidebar link options to create a link entry. */
+function makeSidebarLink(opts: MakeLinkOptions & { autogenerate?: undefined }): SidebarManualLink;
 function makeSidebarLink(
-	href: string,
-	label: string,
-	badge?: Badge,
-	attrs?: LinkHTMLAttributes
-): SidebarLink {
+	opts: MakeLinkOptions & { autogenerate: SidebarAutogenerateRouteData }
+): SidebarAutoLink;
+function makeSidebarLink({ attrs, badge, href, label, autogenerate }: MakeLinkOptions) {
 	if (!isAbsoluteUrl(href)) {
 		href = formatPath(href);
 	}
-	return makeLink({ label, href, badge, attrs });
+	return makeLink({ label, href, badge, attrs, autogenerate });
 }
 
 /** Create a link entry */
-function makeLink({
-	attrs = {},
-	badge = undefined,
-	...opts
-}: {
-	label: string;
-	href: string;
-	badge?: Badge | undefined;
-	attrs?: LinkHTMLAttributes | undefined;
-}): SidebarLink {
-	return { type: 'link', ...opts, badge, isCurrent: false, attrs };
+function makeLink({ attrs = {}, badge, autogenerate, ...opts }: MakeLinkOptions): SidebarLink {
+	return {
+		type: 'link',
+		...opts,
+		badge,
+		isCurrent: false,
+		attrs,
+		...(autogenerate ? { autogenerate } : {}),
+	};
 }
 
 /** Test if two paths are equivalent even if formatted differently. */
@@ -273,13 +275,18 @@ function treeify(routes: Route[], locale: string | undefined, baseDir: string):
 }
 
 /** Create a link entry for a given content collection entry. */
-function linkFromRoute(route: Route, attrs?: LinkHTMLAttributes): SidebarLink {
-	return makeSidebarLink(
-		slugToPathname(route.id),
-		route.entry.data.sidebar.label || route.entry.data.title,
-		route.entry.data.sidebar.badge,
-		{ ...attrs, ...route.entry.data.sidebar.attrs }
-	);
+function linkFromRoute(
+	route: Route,
+	attrs: LinkHTMLAttributes | undefined,
+	autogenerate: SidebarAutogenerateRouteData
+): SidebarAutoLink {
+	return makeSidebarLink({
+		href: slugToPathname(route.id),
+		label: route.entry.data.sidebar.label || route.entry.data.title,
+		badge: route.entry.data.sidebar.badge,
+		attrs: { ...attrs, ...route.entry.data.sidebar.attrs },
+		autogenerate,
+	});
 }
 
 /**
@@ -305,18 +312,22 @@ function sortDirEntries(dir: [string, Dir | Route][]): [string, Dir | Route][] {
 	});
 }
 
+interface SidebarDirOptions {
+	collapsed: boolean;
+	attrs: LinkHTMLAttributes | undefined;
+}
+
+interface SidebarDirContext extends SidebarDirOptions {
+	fullPath: string;
+	dirName: string;
+	autogenerate: SidebarAutogenerateRouteData;
+}
+
 /** Create a group entry for a given content collection directory. */
-function groupFromDir(
-	dir: Dir,
-	fullPath: string,
-	dirName: string,
-	currentPathname: string,
-	locale: string | undefined,
-	collapsed: boolean,
-	attrs?: LinkHTMLAttributes
-): SidebarGroup {
+function groupFromDir(dir: Dir, context: SidebarDirContext): SidebarAutoGroup {
+	const { fullPath, dirName, collapsed, autogenerate } = context;
 	const entries = sortDirEntries(Object.entries(dir)).map(([key, dirOrRoute]) =>
-		dirToItem(dirOrRoute, `${fullPath}/${key}`, key, currentPathname, locale, collapsed, attrs)
+		dirToItem(dirOrRoute, { ...context, fullPath: `${fullPath}/${key}`, dirName: key })
 	);
 	return {
 		type: 'group',
@@ -324,34 +335,29 @@ function groupFromDir(
 		entries,
 		collapsed,
 		badge: undefined,
+		autogenerate,
 	};
 }
 
 /** Create a sidebar entry for a directory or content entry. */
 function dirToItem(
 	dirOrRoute: Dir[string],
-	fullPath: string,
-	dirName: string,
-	currentPathname: string,
-	locale: string | undefined,
-	collapsed: boolean,
-	attrs?: LinkHTMLAttributes
-): SidebarEntry {
+	context: SidebarDirContext
+): SidebarAutoGroup | SidebarAutoLink {
+	const { attrs, autogenerate } = context;
 	return isDir(dirOrRoute)
-		? groupFromDir(dirOrRoute, fullPath, dirName, currentPathname, locale, collapsed, attrs)
-		: linkFromRoute(dirOrRoute, attrs);
+		? groupFromDir(dirOrRoute, context)
+		: linkFromRoute(dirOrRoute, attrs, autogenerate);
 }
 
 /** Create a sidebar entry for a given content directory. */
 function sidebarFromDir(
 	tree: Dir,
-	currentPathname: string,
-	locale: string | undefined,
-	collapsed: boolean,
-	attrs?: LinkHTMLAttributes
+	options: SidebarDirOptions,
+	autogenerate: SidebarAutogenerateRouteData = rootAutogenerate
 ) {
 	return sortDirEntries(Object.entries(tree)).map(([key, dirOrRoute]) =>
-		dirToItem(dirOrRoute, key, key, currentPathname, locale, collapsed, attrs)
+		dirToItem(dirOrRoute, { ...options, fullPath: key, dirName: key, autogenerate })
 	);
 }
 
@@ -374,7 +380,7 @@ const lastCurrentEntryByLocale = new Map<string | undefined, SidebarLink>();
 export function getSidebar(pathname: string, locale: string | undefined): SidebarEntry[] {
 	let intermediateSidebar = intermediateSidebars.get(locale);
 	if (!intermediateSidebar) {
-		intermediateSidebar = getIntermediateSidebarFromConfig(config.sidebar, pathname, locale);
+		intermediateSidebar = getIntermediateSidebarFromConfig(config.sidebar, locale);
 		intermediateSidebars.set(locale, intermediateSidebar);
 	}
 	setIntermediateSidebarCurrentEntry(intermediateSidebar, pathname, locale);
@@ -387,24 +393,23 @@ export function getSidebarFromConfig(
 	pathname: string,
 	locale: string | undefined
 ): SidebarEntry[] {
-	const sidebar = getIntermediateSidebarFromConfig(sidebarConfig, pathname, locale);
+	const sidebar = getIntermediateSidebarFromConfig(sidebarConfig, locale);
 	const currentEntry = getSidebarCurrentEntry(sidebar, pathname);
 	if (currentEntry) currentEntry.isCurrent = true;
 	return sidebar;
 }
 
-/** Get the intermediate sidebar for the current page using the specified sidebar config. */
+/** Get the intermediate sidebar for a locale using the specified sidebar config. */
 function getIntermediateSidebarFromConfig(
 	sidebarConfig: StarlightConfig['sidebar'],
-	pathname: string,
 	locale: string | undefined
 ): SidebarEntry[] {
 	const routes = getLocaleRoutes(locale);
 	if (sidebarConfig) {
-		return sidebarConfig.map((group) => configItemToEntry(group, pathname, locale, routes));
+		return sidebarConfig.flatMap((group) => configItemToEntry(group, locale, routes));
 	} else {
 		const tree = treeify(routes, locale, locale || '');
-		return sidebarFromDir(tree, pathname, locale, false);
+		return sidebarFromDir(tree, { collapsed: false, attrs: undefined });
 	}
 }
 

package/utils/plugins.ts

@@ -199,6 +199,8 @@ const baseStarlightPluginSchema = z.object({
 type StarlightConfigUpdate = Partial<Omit<StarlightUserConfig, 'routeMiddleware'>>;
 type StarlightI18nTFactory = Awaited<ReturnType<typeof createTranslationSystemFromFs>>;
 
+/* eslint-disable @typescript-eslint/no-unnecessary-type-assertion --
+	 The configSetupHookSchema casts `z.any()` to provide types but this rule can’t understand that. */
 const configSetupHookSchema = z
 	.function({
 		input: [

package/utils/routing/types.ts

@@ -14,7 +14,11 @@ export interface LocaleData {
 	locale: string | undefined;
 }
 
-export interface SidebarLink {
+export interface SidebarAutogenerateRouteData {
+	directory: string;
+}
+
+export interface SidebarManualLink {
 	type: 'link';
 	label: string;
 	href: string;
@@ -23,7 +27,11 @@ export interface SidebarLink {
 	attrs: LinkHTMLAttributes;
 }
 
-export interface SidebarGroup {
+export interface SidebarAutoLink extends SidebarManualLink {
+	autogenerate: SidebarAutogenerateRouteData;
+}
+
+export interface SidebarManualGroup {
 	type: 'group';
 	label: string;
 	entries: (SidebarLink | SidebarGroup)[];
@@ -31,6 +39,12 @@ export interface SidebarGroup {
 	badge: Badge | undefined;
 }
 
+export interface SidebarAutoGroup extends SidebarManualGroup {
+	autogenerate: SidebarAutogenerateRouteData;
+}
+
+export type SidebarLink = SidebarManualLink | SidebarAutoLink;
+export type SidebarGroup = SidebarManualGroup | SidebarAutoGroup;
 export type SidebarEntry = SidebarLink | SidebarGroup;
 
 export interface PaginationLinks {