# Configuration Reference

## Configure the `starlight` integration

Starlight is an integration built on top the [Astro](https://astro.build) web framework. You can configure your project inside the `astro.config.mjs` configuration file:

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My delightful docs site',
		}),
	],
});
```

You can pass the following options to the `starlight` integration.

### `title` (required)

**type:** `string | Record<string, string>`

Set the title for your website. Will be used in metadata and in the browser tab title.

The value can be a string, or for multilingual sites, an object with values for each different locale.
When using the object form, the keys must be BCP-47 tags (e.g. `en`, `ar`, or `zh-CN`):

```ts
starlight({
	title: {
		en: 'My delightful docs site',
		de: 'Meine bezaubernde Dokumentationsseite',
	},
});
```

### `description`

**type:** `string`

Set the description for your website. Used in metadata shared with search engines in the `<meta name="description">` tag if `description` is not set in a page’s frontmatter.

### `logo`

**type:** [`LogoConfig`](#logoconfig)

Set a logo image to show in the navigation bar alongside or instead of the site title. You can either set a single `src` property or set separate image sources for `light` and `dark`.

```js
starlight({
	logo: {
		src: './src/assets/my-logo.svg',
	},
});
```

#### `LogoConfig`

```ts
type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
	| { src: string }
	| { light: string; dark: string }
);
```

### `tableOfContents`

**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number }`\
**default:** `{ minHeadingLevel: 2, maxHeadingLevel: 3 }`

Configure the table of contents shown on the right of each page. By default, `<h2>` and `<h3>` headings will be included in this table of contents.

### `editLink`

**type:** `{ baseUrl: string }`

Enable “Edit this page” links by setting the base URL these should use. The final link will be `editLink.baseUrl` + the current page path. For example, to enable editing pages in the `withastro/starlight` repo on GitHub:

```js
starlight({
	editLink: {
		baseUrl: 'https://github.com/withastro/starlight/edit/main/',
	},
});
```

With this config, a `/introduction` page would have an edit link pointing to `https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md`.

### `sidebar`

**type:** [`SidebarItem[]`](#sidebaritem)

Configure your site’s sidebar navigation items.

A sidebar is an array of links, groups of links, and autogenerated entries.
Sidebar items are defined using one of the following properties:

- `link` — a single link to a specific URL, e.g. `'/home'` or `'https://example.com'`. A link must also have a `label`.

- `slug` — a reference to an internal page, e.g. `'guides/getting-started'`. The linked page’s title will be used as the label by default.

- `items` — an array containing more sidebar links, subgroups, and autogenerated entries. A group must also have a `label`.

- `autogenerate` — an object specifying a directory of your docs to automatically generate links and subgroups for. Autogenerated entries can be placed in a group’s `items` array.

Internal links can also be specified as a string instead of an object with a `slug` property.

```js
starlight({
	sidebar: [
		// A single link item labelled “Home”.
		{ label: 'Home', link: '/' },
		// A group labelled “Start Here” containing four links.
		{
			label: 'Start Here',
			items: [
				// Using `slug` for internal links.
				{ slug: 'intro' },
				{ slug: 'installation' },
				// Or using the shorthand for internal links.
				'tutorial',
				'next-steps',
			],
		},
		// A group linking to all pages in the reference directory.
		{
			label: 'Reference',
			items: [{ autogenerate: { directory: 'reference' } }],
		},
	],
});
```

#### Sorting

Autogenerated sidebar groups are sorted by filename alphabetically.
For example, a page generated from `astro.md` would appear above the page for `starlight.md`.

#### Collapsing groups

Groups of links are expanded by default. You can change this behavior by setting a group’s `collapsed` property to `true`.

Autogenerated subgroups are also expanded by default. Set the `autogenerate.collapsed` property to collapse them.

```js {5,15}
sidebar: [
  // A collapsed group of links.
  {
    label: 'Collapsed Links',
    collapsed: true,
    items: ['intro', 'next-steps'],
  },
  // An expanded group containing collapsed autogenerated subgroups.
  {
    label: 'Reference',
    items: [
      {
        autogenerate: {
          directory: 'reference',
          collapsed: true,
        },
      },
    ],
  },
],
```

#### Translating labels

If your site is multilingual, each item’s `label` is considered to be in the default locale. You can set a `translations` property to provide labels for your other supported languages:

```js {5,9,14}
sidebar: [
  // An example sidebar with labels translated to Brazilian Portuguese.
  {
    label: 'Start Here',
    translations: { 'pt-BR': 'Comece Aqui' },
    items: [
      {
        label: 'Getting Started',
        translations: { 'pt-BR': 'Introdução' },
        link: '/getting-started',
      },
      {
        label: 'Project Structure',
        translations: { 'pt-BR': 'Estrutura de Projetos' },
        link: '/structure',
      },
    ],
  },
],
```

#### `SidebarItem`

```ts
type SidebarItem =
	| string
	| ({
			translations?: Record<string, string>;
			badge?: string | BadgeConfig;
	  } & (
			| {
					// Link
					link: string;
					label: string;
					attrs?: Record<string, string | number | boolean | undefined>;
			  }
			| {
					// Internal link
					slug: string;
					label?: string;
					attrs?: Record<string, string | number | boolean | undefined>;
			  }
			| {
					// Group of links
					label: string;
					items: SidebarItem[];
					collapsed?: boolean;
			  }
	  ))
	| {
			// Autogenerated links and subgroups
			autogenerate: {
				directory: string;
				collapsed?: boolean;
				attrs?: Record<string, string | number | boolean | undefined>;
			};
	  };
```

#### `BadgeConfig`

```ts
interface BadgeConfig {
	text: string;
	variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
	class?: string;
}
```

### `locales`

**type:** `\{ \[dir: string\]: [LocaleConfig](#localeconfig) \}`

[Configure internationalization (i18n)](/guides/guides-i18n) for your site by setting which `locales` are supported.

Each entry should use the directory where that language’s files are saved as the key.

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Site',
			// Set English as the default language for this site.
			defaultLocale: 'en',
			locales: {
				// English docs in `src/content/docs/en/`
				en: {
					label: 'English',
				},
				// Simplified Chinese docs in `src/content/docs/zh-cn/`
				'zh-cn': {
					label: '简体中文',
					lang: 'zh-CN',
				},
				// Arabic docs in `src/content/docs/ar/`
				ar: {
					label: 'العربية',
					dir: 'rtl',
				},
			},
		}),
	],
});
```

#### `LocaleConfig`

```ts
interface LocaleConfig {
	label: string;
	lang?: string;
	dir?: 'ltr' | 'rtl';
}
```

You can set the following options for each locale:

##### `label` (required)

**type:** `string`

The label for this language to show to users, for example in the language switcher. Most often you will want this to be the language’s name as a user of that language would expect to read it, e.g. `"English"`, `"العربية"`, or `"简体中文"`.

##### `lang`

**type:** `string`

The BCP-47 tag for this language, e.g. `"en"`, `"ar"`, or `"zh-CN"`. If not set, the language’s directory name will be used by default. Language tags with regional subtags (e.g. `"pt-BR"` or `"en-US"`) will use built-in UI translations for their base language if no region-specific translations are found.

##### `dir`

**type:** `'ltr' | 'rtl'`

The writing direction of this language; `"ltr"` for left-to-right (the default) or `"rtl"` for right-to-left.

#### Root locale

You can serve the default language without a `/lang/` directory by setting a `root` locale:

```js {3-6}
starlight({
	locales: {
		root: {
			label: 'English',
			lang: 'en',
		},
		fr: {
			label: 'Français',
		},
	},
});
```

For example, this allows you to serve `/getting-started/` as an English route and use `/fr/getting-started/` as the equivalent French page.

### `defaultLocale`

**type:** `string`

Set the language which is the default for this site.
The value should match one of the keys of your [`locales`](#locales) object.
(If your default language is your [root locale](#root-locale), you can skip this.)

The default locale will be used to provide fallback content where translations are missing.

### `social`

**type:** `Array<{ label: string; icon: [StarlightIcon](/reference/icons/); href: string }>`

Optional details about the social media accounts for this site.
Each entry will be displayed as an icon link in the site header.

```js
starlight({
	social: [
		{ icon: 'codeberg', label: 'Codeberg', href: 'https://codeberg.org/knut' },
		{ icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
		{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro' },
		{ icon: 'gitlab', label: 'GitLab', href: 'https://gitlab.com/delucis' },
		{ icon: 'mastodon', label: 'Mastodon', href: 'https://m.webtoo.ls/@astro' },
	],
}),
```

### `customCss`

**type:** `string[]`

Provide CSS files to customize the look and feel of your Starlight site.

Supports local CSS files relative to the root of your project, e.g. `'./src/custom.css'`, and CSS you installed as an npm module, e.g. `'@fontsource/roboto'`.

```js
starlight({
	customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});
```

### `markdown`

**type:** `{ headingLinks?: boolean; processedDirs?: string[] }`\
**default:** `{ headingLinks: true, processedDirs: [] }`

Configure Starlight’s Markdown processing.

#### `headingLinks`

**type:** `boolean`\
**default:** `true`

Controls whether or not headings are rendered with a clickable anchor link.

```js
starlight({
	markdown: {
		// Disable Starlight’s clickable heading anchor links.
		headingLinks: false,
	},
}),
```

#### `processedDirs`

**type:** `string[]`\
**default:** `[]`

Define additional directories where files should be processed by Starlight’s Markdown pipeline.
By default, only Markdown and MDX content loaded using Starlight's [`docsLoader()`](/guides/reference-configuration#docsloader) is processed.
Supports local directories relative to the root of your project, e.g. `'./src/data/comments/'`.

Starlight’s processing includes support for [clickable heading anchor links](#headinglinks), [asides Markdown directive syntax](/guides/guides-authoring-content#asides), and RTL support for code blocks.
This option can be useful if you are rendering content from a custom content collection in a [custom page](/guides/guides-pages#custom-pages) using the `<StarlightPage>` component and expect Starlight's Markdown processing to be applied to that content as well.

```js
starlight({
	markdown: {
		// Process Markdown files from the `reviews` content collection located in the
		// `src/data/reviews/` directory.
		processedDirs: ['./src/data/reviews/'],
	},
}),
```

### `expressiveCode`

**type:** `StarlightExpressiveCodeOptions | boolean`\
**default:** `true`

Starlight uses [Expressive Code](https://expressive-code.com) to render code blocks and add support for highlighting parts of code examples, adding filenames to code blocks, and more.
See the [“Code blocks” guide](/guides/guides-authoring-content#code-blocks) to learn how to use Expressive Code syntax in your Markdown and MDX content.

You can use any of the standard [Expressive Code configuration options](https://expressive-code.com/reference/configuration/) as well as some Starlight-specific properties, by setting them in Starlight’s `expressiveCode` option.
For example, set Expressive Code’s `styleOverrides` option to override the default CSS. This enables customizations like giving your code blocks rounded corners:

```js ins={2-4}
starlight({
	expressiveCode: {
		styleOverrides: { borderRadius: '0.5rem' },
	},
});
```

If you want to disable Expressive Code, set `expressiveCode: false` in your Starlight config:

```js ins={2}
starlight({
	expressiveCode: false,
});
```

In addition to the standard Expressive Code options, you can also set the following Starlight-specific properties in your `expressiveCode` config to further customize theme behavior for your code blocks :

#### `themes`

**type:** `Array<string | ThemeObject | ExpressiveCodeTheme>`\
**default:** `['starlight-dark', 'starlight-light']`

Set the themes used to style code blocks.
See the [Expressive Code `themes` documentation](https://expressive-code.com/guides/themes/) for details of the supported theme formats.

Starlight uses the dark and light variants of Sarah Drasner’s [Night Owl theme](https://github.com/sdras/night-owl-vscode-theme) by default.

If you provide at least one dark and one light theme, Starlight will automatically keep the active code block theme in sync with the current site theme.
Configure this behavior with the [`useStarlightDarkModeSwitch`](#usestarlightdarkmodeswitch) option.

#### `useStarlightDarkModeSwitch`

**type:** `boolean`\
**default:** `true`

When `true`, code blocks automatically switch between light and dark themes when the site theme changes.
When `false`, you must manually add CSS to handle switching between multiple themes.

:::callout{intent="note"}
When setting `themes`, you must provide at least one dark and one light theme for the Starlight dark mode switch to work.
:::

#### `useStarlightUiThemeColors`

**type:** `boolean`\
**default:** `true` if `themes` is not set, otherwise `false`

When `true`, Starlight's CSS variables are used for the colors of code block UI elements (backgrounds, buttons, shadows etc.), matching the [site color theme](/guides/guides-css-and-tailwind#theming).
When `false`, the colors provided by the active syntax highlighting theme are used for these elements.

:::callout{intent="note"}
When using custom themes and setting this to `true`, you must provide at least one dark and one light theme to ensure proper color contrast.
:::

### `pagefind`

**type:** `boolean | [PagefindOptions](#pagefindoptions)`\
**default:** `true`

Configure Starlight’s default site search provider [Pagefind](https://pagefind.app/).

Set to `false` to disable indexing your site with Pagefind.
This will also hide the default search UI if in use.

Pagefind cannot be enabled when the [`prerender`](#prerender) option is set to `false`.

Set `pagefind` to an object to configure the Pagefind search client:

- See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) in the Pagefind documentation for more details about using the `pagefind.ranking` option to control how search result ranking is calculated
- See [“Searching multiple sites”](https://pagefind.app/docs/multisite/) in the Pagefind documentation for more details about using the `pagefind.mergeIndex` option to control how to search across multiple sites

#### `PagefindOptions`

```ts
interface PagefindOptions {
	ranking?: PagefindRankingOptions;
	indexWeight?: number;
	mergeIndex?: Array<{
		bundlePath: string;
		indexWeight?: number;
		basePath?: string;
		baseUrl?: string;
		mergeFilter?: Record<string, string | string[]>;
		language?: string;
		ranking?: PagefindRankingOptions;
	}>;
}

interface PagefindRankingOptions {
	pageLength?: number;
	termFrequency?: number;
	termSaturation?: number;
	termSimilarity?: number;
	diacriticSimilarity?: number;
	metaWeights?: Record<string, number>;
}
```

### `prerender`

**type:** `boolean`\
**default:** `true`

Define whether Starlight pages should be pre-rendered to static HTML or on-demand rendered by an [SSR adapter](https://docs.astro.build/en/guides/on-demand-rendering/).

Starlight pages are pre-rendered by default.
If you are using an SSR adapter and want to render Starlight pages on demand, set `prerender: false`.

### `head`

**type:** [`HeadConfig[]`](#headconfig)

Add custom tags to the `<head>` of your Starlight site.
Can be useful for adding analytics and other third-party scripts and resources.

```js
starlight({
	head: [
		// Example: add Fathom analytics script tag.
		{
			tag: 'script',
			attrs: {
				src: 'https://cdn.usefathom.com/script.js',
				'data-site': 'MY-FATHOM-ID',
				defer: true,
			},
		},
	],
});
```

Entries in `head` are converted directly to HTML elements and do not pass through Astro’s [script](https://docs.astro.build/en/guides/client-side-scripts/#script-processing) or [style](https://docs.astro.build/en/guides/styling/#styling-in-astro) processing.
If you need to import local assets like scripts, styles, or images, [override the Head component](/guides/guides-overriding-components#reuse-a-built-in-component).

#### `HeadConfig`

```ts
interface HeadConfig {
	tag: string;
	attrs?: Record<string, string | boolean | undefined>;
	content?: string;
}
```

### `lastUpdated`

**type:** `boolean`\
**default:** `false`

Control whether the footer shows when the page was last updated.

By default, this feature relies on your repository’s Git history and may not be accurate on some deployment platforms performing [shallow clones](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). A page can override this setting or the Git-based date using the [`lastUpdated` frontmatter field](/guides/reference-frontmatter#lastupdated).

### `pagination`

**type:** `boolean`\
**default:** `true`

Define if the footer should include previous and next page links.

A page can override this setting or the link text and/or URL using the [`prev`](/guides/reference-frontmatter#prev) and [`next`](/guides/reference-frontmatter#next) frontmatter fields.

### `favicon`

**type:** `string`\
**default:** `'/favicon.svg'`

Set the path of the default favicon for your website which should be located in the `public/` directory and be a valid (`.ico`, `.gif`, `.jpg`, `.png`, or `.svg`) icon file.

```js
starlight({
  favicon: '/images/favicon.svg',
}),
```

If you need to set additional variants or fallback favicons, you can add tags using the [`head` option](#head):

```js
starlight({
	favicon: '/images/favicon.svg',
	head: [
		// Add ICO favicon fallback for Safari.
		{
			tag: 'link',
			attrs: {
				rel: 'icon',
				href: '/images/favicon.ico',
				sizes: '32x32',
			},
		},
	],
});
```

### `titleDelimiter`

**type:** `string`\
**default:** `'|'`

Sets the delimiter between page title and site title in the page’s `<title>` tag, which is displayed on browser tabs.

By default, every page has a `<title>` of `Page Title | Site Title`.
For example, this page is titled “Configuration Reference” and this site is titled “Starlight”, so the `<title>` for this page is “Configuration Reference | Starlight”.

### `disable404Route`

**type:** `boolean`\
**default:** `false`

Disables injecting Starlight's default [404 page](https://docs.astro.build/en/basics/astro-pages/#custom-404-error-page). To use a custom `src/pages/404.astro` route in your project, set this option to `true`.

### `routeMiddleware`

**type:** `string | string[]`

Provide paths to route middleware that can modify how Starlight processes your data.
These file paths must not conflict with [Astro’s middleware](https://docs.astro.build/en/guides/middleware/).

See the [Route Data guide](/guides/guides-route-data#customizing-route-data) for details about how to create route middleware.

### `components`

**type:** `Record<string, string>`

Provide the paths to components to override Starlight’s default implementations.

```js
starlight({
	components: {
		SocialLinks: './src/components/MySocialLinks.astro',
	},
});
```

See the [Overrides Reference](/guides/reference-overrides) for details of all the components that you can override.

### `plugins`

**type:** [`StarlightPlugin[]`](/guides/reference-plugins#quick-api-reference)

Extend Starlight with custom plugins.
Plugins apply changes to your project to modify or add to Starlight's features.

Visit the [plugins showcase](/guides/resources-plugins#plugins) to see a list of available plugins.

```js
starlight({
	plugins: [starlightPlugin()],
});
```

See the [Plugins Reference](/guides/reference-plugins) for details about creating your own plugins.

### `credits`

**type:** `boolean`\
**default:** `false`

Enable displaying a “Built with Starlight” link in your site’s footer.

```js
starlight({
	credits: true,
});
```

## Configure content collections

Starlight uses Astro [content collections](https://docs.astro.build/en/guides/content-collections/) to load your content.
Starlight’s content loaders and schemas help configure collections as required.

```js
// src/content.config.ts
import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
	// Optional: the i18n collection is used to translate UI in multilingual sites
	i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};
```

### Loaders

Starlight exports the following [Astro loaders](https://docs.astro.build/en/reference/content-loader-reference/) from the `@astrojs/starlight/loaders` module to simplify configuring content collections.

#### `docsLoader()`

The `docsLoader()` loads local Markdown, MDX, and Markdoc files from the `src/content/docs/` directory.
File names starting with an underscore (`_`) are ignored.

##### Import

```js
import { docsLoader } from '@astrojs/starlight/loaders';
```

##### Options

###### `generateId()`

**type:** `({ entry: string; base: URL; data: Record<string, unknown> }) => string`

By default, pages generated using `docsLoader()` process your file names using a sluggifier, which removes special characters and lowercases the file name.
If you want to override this default, provide your own custom `generateId()` function.

For example, this can be useful to preserve special characters that would be removed.
By default, `Example.File.md` would be served at `/examplefile`.
If you wanted to serve it at `/Example.File`, you could do so by defining a custom `generateId()` function:

```js
docsLoader({
	// Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
	generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),
```

See [`generateId()` in the Astro docs](https://docs.astro.build/en/reference/content-loader-reference/#generateid) for more details.

#### `i18nLoader()`

The `i18nLoader()` loads local JSON and YAML files from the `src/content/i18n/` directory.
File names starting with an underscore (`_`) are ignored.

##### Import

```js
import { i18nLoader } from '@astrojs/starlight/loaders';
```

##### Options

There are currently no options to configure `i18nLoader()`.

### Schemas

Starlight provides the following [content collection schemas](https://docs.astro.build/en/guides/content-collections/#defining-the-collection-schema) from the `@astrojs/starlight/schema` module.
These schemas must be used for the `docs` and `i18n` collections Starlight depends on.

#### `docsSchema()`

The `docsSchema()` parses frontmatter for all your content in the `docs` collection.

##### Import

```js
import { docsSchema } from '@astrojs/starlight/schema';
```

##### Options

###### `extend`

**type:** Zod schema or function that returns a Zod schema\
**default:** `z.object({})`

Extend Starlight’s frontmatter schema with additional fields.
See [“Customize frontmatter schema”](/guides/reference-frontmatter#customize-frontmatter-schema) for more details about using the `extend` option.

#### `i18nSchema()`

The `i18nSchema()` parses all data files in the `i18n` collection.

##### Import

```js
import { i18nSchema } from '@astrojs/starlight/schema';
```

##### Options

###### `extend`

**type:** Zod object\
**default:** `z.object({})`

Extend Starlight’s i18n schema with additional fields.
See [“Extend translation schema”](/guides/guides-i18n#extend-translation-schema) for more details about using the `extend` option.

## Related pages

- [Starlight](../index.md)
- [Using Components](./components-using-components.md)
- [Pages](./guides-pages.md)
- [Not found](./more-404.md)
- [Plugins and Integrations](./resources-plugins.md)
- [Start Here](./start-here-index.md)
- [Getting Started](./start-here-getting-started.md)
- [Cards](./components-cards.md)
- [Guides](./guides-index.md)
- [Authoring Content in Markdown](./guides-authoring-content.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.