Skip to content
Starlight

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/
        • Directoryconstellations/
          • andromeda.md
          • orion.md
        • Directorystars/
          • betelgeuse.md

The following sidebar will be automatically generated:

Learn more about autogenerated sidebars in the autogenerated groups section.

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.

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:

starlight({
  sidebar: [
    { slug: 'constellations/andromeda' },
    { slug: 'constellations/orion' },
  ],
});

And the following file structure:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryconstellations/
          • 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, and attrs properties.

See “Customizing autogenerated links” for more details about controlling the sidebar appearance from page frontmatter.

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:

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});

Add a link to an external or non-docs page using an object with label and link properties.

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.

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 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.

By default, pages are sorted in alphabetical order according to the file slug.

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: 'Constellations',
      // Autogenerate a group of links for the 'constellations' directory.
      autogenerate: { directory: 'constellations' },
    },
  ],
});

And the following file structure:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryconstellations/
          • carina.md
          • centaurus.md
          • Directoryseasonal/
            • andromeda.md

The following sidebar will be generated:

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.

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
---

An autogenerated group including a page with the frontmatter above will generate the following sidebar:

Badges

Links, groups, and autogenerated groups can also include a badge property to display a badge next to their label.

starlight({
  sidebar: [
    {
      label: 'Stars',
      items: [
        // A link with a "Supergiant" badge.
        {
          slug: 'stars/persei',
          badge: 'Supergiant',
        },
      ],
    },
    // An autogenerated group with an "Outdated" badge.
    {
      label: 'Moons',
      badge: 'Outdated',
      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.

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:

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:

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:

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 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.

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:

Internal links will automatically use translated page titles from content frontmatter by default:

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.

Collapsing groups

Groups of links can be collapsed by default by setting the collapsed property to true.

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Collapse the group by default.
      collapsed: true,
      items: ['constellations/andromeda', 'constellations/orion'],
    },
  ],
});

The configuration above generates the following sidebar:

Autogenerated groups respect the collapsed value of their parent group:

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Collapse the group and its autogenerated subgroups by default.
      collapsed: true,
      autogenerate: { directory: 'constellations' },
    },
  ],
});

The configuration above generates the following sidebar:

This behavior can be overridden by defining the autogenerate.collapsed property.

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Do not collapse the "Constellations" group but collapse its
      // autogenerated subgroups.
      collapsed: false,
      autogenerate: { directory: 'constellations', collapsed: true },
    },
  ],
});

The configuration above generates the following sidebar: