Global `tableOfContents` config ignored due to zod v4 `.default().optional()` behavior change

[pyxelr]

What version of starlight are you using?

0.38.0

What version of astro are you using?

6.0.2

What package manager are you using?

npm

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

Description

In Starlight 0.38.0 (with Astro 6), the global tableOfContents configuration in astro.config.mjs is silently ignored. All pages use the schema defaults (minHeadingLevel: 2, maxHeadingLevel: 3) regardless of the global config.

Reproduction

// astro.config.mjs
starlight({
  tableOfContents: { maxHeadingLevel: 6 },
  // ...
})

Expected: ToC shows headings up to h6.
Actual: ToC only shows h2–h3. The built HTML always has data-max-h="3".

Root cause

In schema.ts#L36, the frontmatter field is defined as:

tableOfContents: TableOfContentsSchema().optional(),

TableOfContentsSchema() includes .default({ minHeadingLevel: 2, maxHeadingLevel: 3 }). In zod v3, chaining .default(x).optional() returned undefined for undefined input. In zod v4 (shipped with Astro 6), it returns the default value instead.

This means entry.data.tableOfContents is always { minHeadingLevel: 2, maxHeadingLevel: 3 }, even when frontmatter doesn't set it. The check in getToC():

entry.data.tableOfContents !== undefined
    ? entry.data.tableOfContents   // ← always taken
    : config.tableOfContents;      // ← never reached

always takes the frontmatter branch, so the global config is never used.

Suggested fix

1. Use an inline schema without .default() for the frontmatter field, so it returns undefined when not set in frontmatter:

tableOfContents: z
    .union([
        z.object({
            minHeadingLevel: z.int().min(1).max(6).optional(),
            maxHeadingLevel: z.int().min(1).max(6).optional(),
        }),
        z.boolean(),
    ])
    .optional(),

2. Update getToC() to merge partial frontmatter values with the global config:

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,
    };
}

Note

This likely affects other fields using the same .default().optional() + !== undefined pattern.

Environment

• starlight: 0.38.0
• astro: 6.0.2
• Package manager: npm
• OS: Mac
• Browser: Chrome

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-t6ykq65o

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for reporting this @pyxelr! Are you interested in making a PR to fix it or would you like us to handle that?

[pyxelr]

@delucis: Sure, I think I can try it out

[delucis]

Thanks! Let us know if you need guidance on anything — happy to help.

[pyxelr]

@delucis: Here is the PR: #3751