fix: respect global tableOfContents config with zod v4

With zod v4, `.default(value).optional()` returns the default value
for `undefined` input instead of `undefined` itself. This caused
frontmatter `tableOfContents` to always resolve to the schema default,
preventing the global Starlight config from being used as a fallback.

This fix introduces a separate `FrontmatterTableOfContentsSchema` that
omits `.default()` so `undefined` is preserved, and updates `getToC()`
to properly merge frontmatter values with the global config.

Closes #3748

Author: pyxelr

.changeset/fix-toc-global-config-zod-v4.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes global `tableOfContents` config being ignored due to a zod v4 behavior change where `.default().optional()` returns the default value for `undefined` input instead of `undefined` itself.

packages/starlight/schema.ts

@@ -2,7 +2,7 @@ import { z } from 'astro/zod';
 import type { SchemaContext } from 'astro:content';
 import { HeadConfigSchema } from './schemas/head';
 import { PrevNextLinkConfigSchema } from './schemas/prevNextLink';
-import { TableOfContentsSchema } from './schemas/tableOfContents';
+import { FrontmatterTableOfContentsSchema, TableOfContentsSchema } from './schemas/tableOfContents';
 import { BadgeConfigSchema } from './schemas/badge';
 import { HeroSchema } from './schemas/hero';
 import { SidebarLinkItemHTMLAttributesSchema } from './schemas/sidebar';
@@ -33,7 +33,7 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 		head: HeadConfigSchema({ source: 'content' }),
 
 		/** Override global table of contents configuration for this page. */
-		tableOfContents: TableOfContentsSchema().optional(),
+		tableOfContents: FrontmatterTableOfContentsSchema(),
 
 		/**
 		 * Set the layout style for this page.

packages/starlight/schemas/tableOfContents.ts

@@ -17,3 +17,22 @@ export const TableOfContentsSchema = () =>
 		.refine((toc) => (toc ? toc.minHeadingLevel <= toc.maxHeadingLevel : true), {
 			error: 'minHeadingLevel must be less than or equal to maxHeadingLevel',
 		});
+
+/**
+ * Schema for the `tableOfContents` frontmatter field.
+ * Unlike `TableOfContentsSchema`, this does not include a `.default()` so that
+ * `undefined` is preserved when the field is not set in frontmatter, allowing
+ * the global config to be used as a fallback.
+ */
+export const FrontmatterTableOfContentsSchema = () =>
+	z
+		.union([
+			z.object({
+				/** The level to start including headings at in the table of contents. Default: 2. */
+				minHeadingLevel: z.int().min(1).max(6).optional(),
+				/** The level to stop including headings at in the table of contents. Default: 3. */
+				maxHeadingLevel: z.int().min(1).max(6).optional(),
+			}),
+			z.boolean(),
+		])
+		.optional();

packages/starlight/utils/routing/data.ts

@@ -61,12 +61,20 @@ export function generateRouteData({
 }
 
 export function getToC({ entry, lang, headings }: PageProps) {
-	const tocConfig =
-		entry.data.template === 'splash'
-			? false
-			: entry.data.tableOfContents !== undefined
-				? entry.data.tableOfContents
-				: config.tableOfContents;
+	const frontmatterToC = entry.data.tableOfContents;
+	let tocConfig;
+	if (entry.data.template === 'splash') {
+		tocConfig = false;
+	} else if (frontmatterToC === undefined) {
+		tocConfig = config.tableOfContents;
+	} else if (typeof frontmatterToC === 'boolean') {
+		tocConfig = frontmatterToC ? config.tableOfContents : false;
+	} else {
+		tocConfig = {
+			minHeadingLevel: frontmatterToC.minHeadingLevel ?? config.tableOfContents.minHeadingLevel,
+			maxHeadingLevel: frontmatterToC.maxHeadingLevel ?? config.tableOfContents.maxHeadingLevel,
+		};
+	}
 	if (!tocConfig) return;
 	const t = useTranslations(lang);
 	return {