Configuration Options

This page references all configuration options accepted by the starlight() integration in the astro.config.mjs file.

General Options

`title`

Type: string Required: yes

Documentation site title. Displayed in the header, browser tab, and used for SEO.

title: 'MyProject Documentation';

`description`

Type: string Required: no

Site description used in meta tags for search engine optimization.

description: 'Complete guide to using MyProject.';

`logo`

Type: object Required: no

Logo configuration displayed in the navigation bar.

logo: {
  src: './src/assets/logo.svg',
  alt: 'MyProject Logo',
  replacesTitle: false,
}

Property	Type	Default	Description
`src`	`string`	—	Path to the image file.
`alt`	`string`	`''`	Alt text for accessibility.
`replacesTitle`	`boolean`	`false`	Replace text title with the logo.

`tableOfContents`

Type: object | false Required: no

Controls the table of contents displayed on the right side of pages. Set to false to disable it entirely.

tableOfContents: {
  minHeadingLevel: 2,
  maxHeadingLevel: 3,
}

Property	Type	Default	Description
`minHeadingLevel`	`number`	`2`	Minimum heading level to include.
`maxHeadingLevel`	`number`	`3`	Maximum heading level to include.

`defaultTheme`

Type: 'light' | 'dark' | 'auto' Default: 'auto'

Theme applied on first visit. 'auto' mode follows the user’s system preference.

defaultTheme: 'dark';

`sidebar`

Type: SidebarGroup[] Required: no

Navigation sidebar structure.

sidebar: [
  {
    label: 'Guide',
    items: [
      { label: 'Introduction', slug: 'docs/introduction' },
      { label: 'Installation', slug: 'docs/installation' },
    ],
  },
  {
    label: 'Reference',
    autogenerate: { directory: 'docs/reference' },
  },
];

Each group accepts:

Property	Type	Description
`label`	`string`	Group title.
`translations`	`Record<string, string>`	Label translations (i18n).
`collapsed`	`boolean`	Group collapsed by default.
`items`	`SidebarItem[]`	Group entries.
`autogenerate`	`{ directory: string }`	Generate entries from a directory.

Each sidebar item accepts:

Property	Type	Description
`label`	`string`	Displayed text.
`slug`	`string`	File path (without `src/content/docs/`).
`badge`	`string`	Small badge displayed next to the label.
`attrs`	`object`	HTML attributes added to the link.

`social`

Type: SocialLink[] Required: no

Social links displayed in the site header.

social: [
  {
    icon: 'github',
    label: 'GitHub',
    href: 'https://github.com/my-project',
  },
  {
    icon: 'discord',
    label: 'Discord',
    href: 'https://discord.gg/invite',
  },
];

Available icons: github, gitlab, discord, x, mastodon, youtube, twitch, linkedin, instagram, threads, bluesky, facebook, rss.

`footer`

Type: object Required: no

Footer configuration.

footer: {
  message: '© 2026 MyProject. All rights reserved.',
  href: 'https://my-project.com/legal',
}

`credits`

Type: boolean Default: false

Shows the “Built with Starlight” notice in the footer.

credits: true;

Internationalization

`locales`

Type: Record<string, LocaleConfig> Required: no

Configures the languages supported by the site.

locales: {
  root: { label: 'Français', lang: 'fr' },
  en: { label: 'English', lang: 'en' },
}

`defaultLocale`

Type: object Required: no

Defines the default locale when the root is used for a specific language.

defaultLocale: {
  label: 'Français',
  lang: 'fr',
}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.