Apply suggestions from code review

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

Author: pyxelr

packages/starlight/schemas/tableOfContents.ts

@@ -35,4 +35,20 @@ export const FrontmatterTableOfContentsSchema = () =>
 			}),
 			z.boolean(),
 		])
-		.optional();
+const TableOfContentsBaseSchema = 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().default(2),
+			/** The level to stop including headings at in the table of contents. Default: 3. */
+			maxHeadingLevel: z.int().min(1).max(6).optional().default(3),
+		}),
+		z.boolean().transform((enabled) => (enabled ? defaults : false)),
+	])
+	.refine((toc) => (toc ? toc.minHeadingLevel <= toc.maxHeadingLevel : true), {
+		error: 'minHeadingLevel must be less than or equal to maxHeadingLevel',
+	});
+
+export const UserConfigTableOfContentsSchema = () => TableOfContentsBaseSchema.default(defaults);
+
+export const FrontmatterTableOfContentsSchema = () => TableOfContentsBaseSchema.optional();

packages/starlight/utils/routing/data.ts

@@ -61,26 +61,12 @@ export function generateRouteData({
 }
 
 export function getToC({ entry, lang, headings }: PageProps) {
-	if (entry.data.template === 'splash') return;
-
-	const frontmatterToC = entry.data.tableOfContents;
-	const globalToC = config.tableOfContents;
-
-	// Resolve the effective ToC config from frontmatter and global settings.
-	let tocConfig: false | { minHeadingLevel: number; maxHeadingLevel: number };
-	if (frontmatterToC === undefined || frontmatterToC === true) {
-		// No override or explicit enable — use global config.
-		tocConfig = globalToC;
-	} else if (typeof frontmatterToC === 'object' && globalToC !== false) {
-		// Partial override — merge with global config for missing values.
-		tocConfig = {
-			minHeadingLevel: frontmatterToC.minHeadingLevel ?? globalToC.minHeadingLevel,
-			maxHeadingLevel: frontmatterToC.maxHeadingLevel ?? globalToC.maxHeadingLevel,
-		};
-	} else {
-		tocConfig = false;
-	}
-
+	const tocConfig =
+		entry.data.template === 'splash'
+			? false
+			: entry.data.tableOfContents !== undefined
+				? entry.data.tableOfContents
+				: config.tableOfContents;
 	if (!tocConfig) return;
 	const t = useTranslations(lang);
 	return {