Skip to content
Celestia Theme

Multi-Sidebar

The theme can turn every top-level entry of the Starlight sidebar config into its own sidebar, with a switcher to move between them.

Setup

Set the multiSidebar option on the theme plugin:

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightCelestiaTheme({
          multiSidebar: {
            switcherStyle: "horizontalList",
          },
        }),
      ],
      sidebar: [
        {
          label: "Guide",
          autogenerate: { directory: "guide" },
        },
        {
          label: "API",
          autogenerate: { directory: "api" },
        },
      ],
    }),
  ],
});

Earlier releases documented @lorenzo_lewis/starlight-utils for this. That package is deprecated on npm and is no longer a dependency of the theme, so drop it from your plugin array and your package.json when you move the option across.

The theme groups the sidebar while the Sidebar component renders instead of in a route middleware, so it works alongside starlight-versions whatever order the two plugins are registered in.

Switcher Styles

Horizontal List

The default style. Renders tabs above the sidebar content.

starlightCelestiaTheme({
  multiSidebar: {
    switcherStyle: "horizontalList",
  },
});

A compact dropdown menu for switching between sidebars.

starlightCelestiaTheme({
  multiSidebar: {
    switcherStyle: "dropdown",
  },
});

Hidden

Hides the switcher entirely, so only the sidebar holding the current page is rendered. Useful when combined with top navigation links.

starlightCelestiaTheme({
  multiSidebar: {
    switcherStyle: "hidden",
  },
});

Groups

Each top-level entry in the sidebar array must be a group with a label. Bare links at the top level are not supported, and the build fails with an error naming the offending entry.

Pages outside every group, such as a splash page at the site root, fall back to the first sidebar.

Auto-generate

Use autogenerate to populate a sidebar group from a directory:

{
  label: 'Guide',
  autogenerate: { directory: 'guide' },
}

Badges

Groups support Starlight’s badge system, and the badge is rendered next to the label in the switcher:

{
  label: 'API',
  badge: 'New',
  autogenerate: { directory: 'api' },
}