A well-organized sidebar is key to a good documentation as it is one of the main ways users will navigate your site. Starlight provides a complete set of options to customize your sidebar layout and content. ## Default sidebar By default, Starlight will automatically generate a sidebar based on the filesystem structure of your documentation, using each file's `title` property as the sidebar entry. For example, given the following file structure: - src/ - content/ - docs/ - constellations/ - andromeda.md - orion.md - stars/ - betelgeuse.md The following sidebar will be automatically generated: Learn more about autogenerated sidebars in the [autogenerated links](#autogenerated-links) section. ## Add links and link groups To configure your sidebar links and groups of links (within a collapsible header), use the [`starlight.sidebar`](/guides/reference-configuration#sidebar) property in `astro.config.mjs`. By combining links and groups, you can create a wide variety of sidebar layouts. ### Internal links Add a link to a page in `src/content/docs/` using an object with the `slug` property. The linked page’s title will be used as the label by default. For example, with the following configuration: ```js "slug:" starlight({ sidebar: [ { slug: 'constellations/andromeda' }, { slug: 'constellations/orion' }, ], }); ``` And the following file structure: - src/ - content/ - docs/ - constellations/ - andromeda.md - orion.md The following sidebar will be generated: To override the values inferred from a linked page’s frontmatter, you can add `label`, [`translations`](#internationalization), and [`attrs`](#custom-html-attributes) properties. See ["Customizing autogenerated links"](#customizing-autogenerated-links-in-frontmatter) for more details about controlling the sidebar appearance from page frontmatter. #### Shorthand for internal links Internal links can also be specified by providing only a string for the page slug as a shorthand. For example, the following configuration is equivalent to the configuration above, which used `slug`: ```js "slug:" starlight({ sidebar: ['constellations/andromeda', 'constellations/orion'], }); ``` ### Other links Add a link to an external or non-docs page using an object with `label` and `link` properties. ```js "label:" "link:" starlight({ sidebar: [ // A link to a non-docs page on this site. { label: 'Meteor Store', link: '/shop/' }, // An external link to the NASA website. { label: 'NASA', link: 'https://www.nasa.gov/' }, ], }); ``` The configuration above generates the following sidebar: ### Groups You can add structure to your sidebar by grouping related links together under a collapsible heading. Groups can contain both links and other sub-groups. Add a group using an object with `label` and `items` properties. The `label` will be used as the heading for the group. Add links or subgroups to the `items` array. ```js /^\s*(label:|items:)/ starlight({ sidebar: [ // A group of links labelled "Constellations". { label: 'Constellations', items: [ 'constellations/carina', 'constellations/centaurus', // A nested group of links for seasonal constellations. { label: 'Seasonal', items: [ 'constellations/andromeda', 'constellations/orion', 'constellations/ursa-minor', ], }, ], }, ], }); ``` The configuration above generates the following sidebar: ### Autogenerated links Starlight can automatically generate links in your sidebar based on a directory of your docs. This is helpful when you do not want to manually enter each sidebar item in a group. By default, pages are sorted in alphabetical order according to the file [`id`](/guides/reference-route-data#id). Add autogenerated links using an object with the `autogenerate` property. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration: ```js "label:" "autogenerate:" starlight({ sidebar: [ { label: 'Constellations', // Autogenerate links for the 'constellations' directory. items: [{ autogenerate: { directory: 'constellations' } }], }, ], }); ``` And the following file structure: - src/ - content/ - docs/ - constellations/ - carina.md - centaurus.md - seasonal/ - andromeda.md The following sidebar will be generated: ## Customizing autogenerated links in frontmatter Use the [`sidebar` frontmatter field](/guides/reference-frontmatter#sidebar) in individual pages to customize autogenerated links. Sidebar frontmatter options allow you to set a [custom label](/guides/reference-frontmatter#label), use [custom attributes](/guides/reference-frontmatter#attrs), add a [badge](/guides/reference-frontmatter#badge) to a link, [hide](/guides/reference-frontmatter#hidden) a link from the sidebar, or define a [custom sort weighting](/guides/reference-frontmatter#order). ```md "sidebar:" --- # src/content/docs/example.md title: My page sidebar: # Set a custom label for the link label: Custom sidebar label # Set a custom order for the link (lower numbers are displayed higher up) order: 2 # Add a badge to the link badge: text: New variant: tip --- ``` A group with autogenerated links including a page with the frontmatter above will generate the following sidebar: :::callout{intent="note"} The `sidebar` frontmatter configuration is only used for autogenerated links and docs links defined with the `slug` property. It does not apply to links defined with the `link` property. ::: ## Badges Links and groups can also include a `badge` property to display a badge next to their label. ```js {9,16} starlight({ sidebar: [ { label: 'Stars', items: [ // A link with a "Supergiant" badge. { slug: 'stars/persei', badge: 'Supergiant', }, ], }, // A group with an "Outdated" badge. { label: 'Moons', badge: 'Outdated', items: [{ autogenerate: { directory: 'moons' } }], }, ], }); ``` The configuration above generates the following sidebar: ### Badge variants and custom styling Customize the badge styling using an object with `text`, `variant`, and `class` properties. The `text` represents the content to display (e.g. "New"). By default, the badge will use the accent color of your site. To use a built-in badge style, set the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`. Optionally, you can create a custom badge style by setting the `class` property to a CSS class name. ```js {9} starlight({ sidebar: [ { label: 'Stars', items: [ // A link with a yellow "Stub" badge. { slug: 'stars/sirius', badge: { text: 'Stub', variant: 'caution' }, }, ], }, ], }); ``` The configuration above generates the following sidebar: Learn more about [using and customizing badges](/guides/components-badges#usage). ## Custom HTML attributes Links can also include an `attrs` property to add custom HTML attributes to the link element. In the following example, `attrs` is used to add a `target="_blank"` attribute, so that the link opens in a new tab, and to apply a custom `style` attribute to italicize the link label: ```js {10} starlight({ sidebar: [ { label: 'Resources', items: [ // An external link to the NASA website opening in a new tab. { label: 'NASA', link: 'https://www.nasa.gov/', attrs: { target: '_blank', style: 'font-style: italic' }, }, ], }, ], }); ``` The configuration above generates the following sidebar: ### Custom HTML attributes for autogenerated links Customize HTML attributes of all [autogenerated links](#autogenerated-links) by defining the `attrs` property in the `autogenerate` configuration. Individual pages can specify custom attributes using the [`sidebar.attrs` frontmatter field](/guides/reference-frontmatter#attrs) which will be merged with the `autogenerate.attrs` configuration. For example, with the following configuration: ```js {8} starlight({ sidebar: [ { autogenerate: { // Autogenerate links for the 'constellations' directory. directory: 'constellations', // Italicize all autogenerated link labels. attrs: { style: 'font-style: italic' }, }, }, ], }); ``` And the following file structure: - src/ - content/ - docs/ - constellations/ - carina.md - centaurus.md - seasonal/ - andromeda.md The following sidebar will be generated with all autogenerated links italicized: ## Internationalization Use the `translations` property on link and group entries to translate the link or group label for each supported language by specifying a [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) language tag, e.g. `"en"`, `"ar"`, or `"zh-CN"`, as the key and the translated label as the value. The `label` property will be used for the default locale and for languages without a translation. ```js {5-7,11-13,18-20} starlight({ sidebar: [ { label: 'Constellations', translations: { 'pt-BR': 'Constelações', }, items: [ { label: 'Andromeda', translations: { 'pt-BR': 'Andrômeda', }, slug: 'constellations/andromeda', }, { label: 'Scorpius', translations: { 'pt-BR': 'Escorpião', }, slug: 'constellations/scorpius', }, ], }, ], }); ``` Browsing the documentation in Brazilian Portuguese will generate the following sidebar: ### Internationalization with internal links [Internal links](#internal-links) will automatically use translated page titles from content frontmatter by default: ```js {9-10} starlight({ sidebar: [ { label: 'Constellations', translations: { 'pt-BR': 'Constelações', }, items: [ { slug: 'constellations/andromeda' }, { slug: 'constellations/scorpius' }, ], }, ], }); ``` Browsing the documentation in Brazilian Portuguese will generate the following sidebar: In multilingual sites, the value of `slug` does not include the language portion of the URL. For example, if you have pages at `en/intro` and `pt-br/intro`, the slug is `intro` when configuring the sidebar. ### Internationalization with badges For [badges](#badges), the `text` property 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](https://www.w3.org/International/questions/qa-choosing-language-tags) tags (e.g. `en`, `ar`, or `zh-CN`): ```js {11-16} starlight({ sidebar: [ { label: 'Constellations', translations: { 'pt-BR': 'Constelações', }, items: [ { slug: 'constellations/andromeda', badge: { text: { en: 'New', 'pt-BR': 'Novo', }, }, }, ], }, ], }); ``` Browsing the documentation in Brazilian Portuguese will generate the following sidebar: ## Collapsing groups Groups of links can be collapsed by default by setting the `collapsed` property to `true`. ```js {5-6} starlight({ sidebar: [ { label: 'Constellations', // Collapse the group by default. collapsed: true, items: ['constellations/andromeda', 'constellations/orion'], }, ], }); ``` The configuration above generates the following sidebar: [Autogenerated subgroups](#autogenerated-links) can also be collapsed by default by setting the `autogenerate.collapsed` property to `true`. ```js {9-10} starlight({ sidebar: [ { label: 'Constellations', items: [ { autogenerate: { directory: 'constellations', // Collapse autogenerated subgroups by default. collapsed: true, }, }, ], }, ], }); ``` The configuration above generates the following sidebar: ## Related pages - [Starlight](../index.md) - [Using Components](./components-using-components.md) - [Pages](./guides-pages.md) - [Not found](./more-404.md) - [Configuration Reference](./reference-configuration.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) # 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.