Skip to content
🧰 Starlight Utils

Multi-Sidebar

There are cases where having multiple sidebars for a Starlight site can be useful. Starlight does not currently support this natively, but this utility gives a minimal implementation of this.

Configuration

Multi-sidebar can be enabled by adding the multiSidebar object to the Starlight Utils configuration.

To define the sidebars, specify a label and contents for each sidebar. Here is a simplified example of the config used for this site:

astro.config.mjs
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightUtils from "@lorenzo_lewis/starlight-utils";


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightUtils({
          multiSidebar: {
            switcherStyle: "horizontalList",
          },
        }),
      ],
      sidebar: [
        {
          label: "Main",
          autogenerate: { directory: "/docs" },
        },
        {
          label: "Demos",
          autogenerate: { directory: "/demos" },
          badge: "New",
        },
      ],
    }),
  ],
});

multiSidebar

Type: boolean | { switcherStyle: "dropdown" | "horizontalList" | "hidden" } | undefined

  • If true, the sidebar will be rendered with the horizontalList switcher style.
  • If no multiSidebar key is set, or if the value is false or undefined, then the default Starlight sidebar will be used.
  • Otherwise, the value specified in switcherStyle will be used.
  • The hidden style hides the sidebar switcher. This is useful if you are using Nav Links and don’t need a sidebar switcher.

Migration

@lorenzo_lewis/starlight-multi-sidebar has been deprecated in favor of this package.

Here are the steps for migrating from @lorenzo_lewis/starlight-multi-sidebar:

  1. Switch to @lorenzo_lewis/starlight-utils by running this command to remove the deprecated package:

    Terminal window
    npm uninstall @lorenzo_lewis/starlight-multi-sidebar

    Then this command to add the new package:

    Terminal window
    npm i @lorenzo_lewis/starlight-utils

  2. Update the integration in astro.config.mts:

    astro.config.mjs
    import { defineConfig } from "astro/config";
    import starlight from "@astrojs/starlight";
    import starlightUtils from "@lorenzo_lewis/starlight-utils";
    import starlightMultiSidebar from "@lorenzo_lewis/starlight-multi-sidebar";
    

    // https://astro.build/config
    export default defineConfig({
      integrations: [
        starlight({
          plugins: [
            starlightUtils({ multiSidebar: true }),
            starlightMultiSidebar(),
          ],
        }),
      ],
    });

    Any configuration options used before are also compatible and can be passed to the multiSidebar object.