1.2 Site Wide Configuration

Default `tableOfContents` Levels

To configure the tableOfContents sitewide in Astro Starlight using an .mjs file, you’ll need to modify the starlight.config.mjs file. The tableOfContents option in Starlight controls the generation of a table of contents (TOC) for your documentation pages.

Step to set this up:

1. Locate or Create `starlight.config.mjs`

If you don’t already have a starlight.config.mjs file, create one at the root of your Astro project.

2. Configure `tableOfContents`

You can configure the tableOfContents option globally in the starlight.config.mjs file by setting it within the Starlight configuration.

Example:

import { defineConfig } from 'astro';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      // Other Starlight options
      theme: {
        tableOfContents: {
          minHeadingLevel: 2, // Minimum heading level to include in TOC (e.g., h2)
          maxHeadingLevel: 3, // Maximum heading level to include in TOC (e.g., h3)
        },
      },
    }),
  ],
});

Explanation:

minHeadingLevel: Specifies the minimum heading level to include in the TOC. For example, if you set it to 2, only h2 and higher headings (h2, h3, etc.) will be included.
maxHeadingLevel: Specifies the maximum heading level to include in the TOC. For example, if you set it to 3, only h2 and h3 headings will be included.

This configuration applies sitewide, so all pages in your Starlight documentation will use the same TOC settings.

3. Build and Test Your Project

After configuring the tableOfContents option, build your project to ensure the settings are applied:

npm run build

Example with Additional Options

If you have other Starlight configurations, they can be combined with the tableOfContents settings:

import { defineConfig } from 'astro';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      // Example: Custom site title
      site: {
        title: 'My Documentation Site',
      },
      // Configure Table of Contents
      theme: {
        tableOfContents: {
          minHeadingLevel: 2,
          maxHeadingLevel: 4,
        },
      },
    }),
  ],
});

By setting this up, you ensure a consistent table of contents across all your documentation pages in Astro Starlight.

Enter Password