Sidebar Navigation
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:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryguides/
- components.md
- i18n.md
Directoryreference/
- configuration.md
The following sidebar will be automatically generated:
Learn more about autogenerated sidebars in the autogenerated groups section.
Add links and link groups
To configure your sidebar links and groups of links (within a collapsible header), use the starlight.sidebar
property in astro.config.mjs
.
By combining links and groups, you can create a wide variety of sidebar layouts.
Links
Add a link to an internal or external page using an object with label
and link
properties.
starlight({
sidebar: [
// A link to the CSS & Styling guide.
{ label: 'CSS & Styling', link: '/guides/css-and-tailwind/' },
// An external link to the Astro website.
{ label: 'Astro', link: 'https://astro.build/' },
],
});
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.
starlight({
sidebar: [
// A group of links labelled "Guides".
{
label: 'Guides',
items: [
{ label: 'Components', link: '/guides/components/' },
{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
// A nested group of links.
{
label: 'Styling',
items: [
{ label: 'CSS', link: '/guides/css-and-tailwind/' },
{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
],
},
],
},
],
});
The configuration above generates the following sidebar:
Autogenerated groups
Starlight can automatically generate a group 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. Pages will be sorted alphabetically by filename by default.
Add an autogenerated group using an object with label
and autogenerate
properties. Your autogenerate
configuration must specify the directory
to use for sidebar entries. For example, with the following configuration:
starlight({
sidebar: [
{
label: 'Guides',
// Autogenerate a group of links for the 'guides' directory.
autogenerate: { directory: 'guides' },
},
],
});
And the following file structure:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryguides/
- components.md
- i18n.md
Directoryadvanced/
- project-structure.md
The following sidebar will be generated:
Customizing autogenerated links in frontmatter
Use the sidebar
frontmatter field in individual pages to customize autogenerated links.
Sidebar frontmatter options allow you to set a custom label or add a badge to a link, hide a link from the sidebar, or define a custom sort weighting.
---
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
---
An autogenerated group including a page with the frontmatter above will generate the following sidebar:
Badges
Links can also include a badge
property to display a badge next to the link label.
starlight({
sidebar: [
{
label: 'Guides',
items: [
// A link with a "New" badge.
{
label: 'Components',
link: '/guides/components/',
badge: 'New',
},
],
},
],
});
The configuration above generates the following sidebar:
Badge variants
Customize the badge styling using an object with text
and variant
properties.
The text
represents the content to display (e.g. “New”).
Override the default
styling, which uses the accent color of your site, by setting the variant
property to one of the following values: note
, tip
, danger
, caution
or success
.
starlight({
sidebar: [
{
label: 'Guides',
items: [
// A link with a yellow "Experimental" badge.
{
label: 'Components',
link: '/guides/components/',
badge: { text: 'Experimental', variant: 'caution' },
},
],
},
],
});
The configuration above generates the following sidebar:
Internationalization
Use the translations
property on link and group entries to translate the link or group label for each supported language.
The label
property will be used for the default locale and for languages without a translation.
starlight({
sidebar: [
{
label: 'Guides',
translations: {
es: 'Guías',
},
items: [
{
label: 'Components',
translations: {
es: 'Componentes',
},
link: '/guides/components/',
},
{
label: 'Internationalization (i18n)',
translations: {
es: 'Internacionalización (i18n)',
},
link: '/guides/i18n/',
},
],
},
],
});
Browsing the documentation in Spanish will generate the following sidebar:
Collapsing groups
Groups of links can be collapsed by default by setting the collapsed
property to true
.
starlight({
sidebar: [
{
label: 'Guides',
// Collapse the group by default.
collapsed: true,
items: [
{ label: 'Components', link: '/guides/components/' },
{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
],
},
],
});
The configuration above generates the following sidebar:
Autogenerated groups respect the collapsed
value of their parent group:
starlight({
sidebar: [
{
label: 'Guides',
// Collapse the group and its autogenerated subgroups by default.
collapsed: true,
autogenerate: { directory: 'guides' },
},
],
});
The configuration above generates the following sidebar:
This behavior can be overridden by defining the autogenerate.collapsed
property.
starlight({
sidebar: [
{
label: 'Guides',
// Do not collapse the "Guides" group but collapse its
// autogenerated subgroups.
collapsed: false,
autogenerate: { directory: 'guides', collapsed: true },
},
],
});
The configuration above generates the following sidebar: