Skip to content
Starlight Auto Sidebar

Getting Started

A Starlight plugin to tweak autogenerated sidebar groups:

  • Rename autogenerated sidebar group directories.
  • Add badges or change the collapsed state of autogenerated sidebar group directories.
  • Manually specify the order of autogenerated sidebar group directories.
  • Change the sorting behavior of autogenerated sidebar groups.
  • Hide autogenerated sidebar group directories.
  • Limit the depth of autogenerated sidebar groups.
  • Cascade some options to all nested autogenerated sidebar group directories.

Check out the demo for a preview of various features provided by the plugin.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

  1. Starlight Auto Sidebar is a Starlight plugin. Install it using your favorite package manager:

    Terminal window
    npm i starlight-auto-sidebar

  2. Add the plugin to your Starlight configuration in the astro.config.mjs file.

    astro.config.mjs
    // @ts-check
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightAutoSidebar from 'starlight-auto-sidebar'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [starlightAutoSidebar()],
          title: 'My Docs',
        }),
      ],
    })

  3. Starlight Auto Sidebar uses Astro’s content collections, which are configured in the src/content.config.ts file.

    Update the content config file to add support for customizing autogenerated sidebar groups using metadata files:

    src/content.config.ts
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    import { defineCollection } from 'astro:content'
    import { autoSidebarLoader } from 'starlight-auto-sidebar/loader'
    import { autoSidebarSchema } from 'starlight-auto-sidebar/schema'
    

    export const collections = {
      docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
      autoSidebar: defineCollection({
        loader: autoSidebarLoader(),
        schema: autoSidebarSchema(),
      }),
    }

  4. Starlight Auto Sidebar uses metadata files located in the directory of an autogenerated sidebar group that you want to customize.

    For example, given the following Starlight src/content/docs/ directory:

    • Directorydocs
      • Directoryguides
        • example.md
      • Directoryreference
        • about.md
        • Directoryapi-reference
          • api.md

    And the given autogenerated sidebar group configuration for the reference/ directory:

    starlight({
      sidebar: [
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    })

    By default, the following sidebar group will be generated:

    To update the api-reference directory label to API Reference, create a metadata file named _meta.yml in the src/content/docs/reference/api-reference/ directory with the following content:

    src/content/docs/reference/api-reference/_meta.yml
    # Set the directory sidebar label to `API Reference`.
    label: API Reference

  5. Start the development server to preview the updated sidebar which should now look like this:

To learn more about metadata files and how to customize autogenerated sidebar groups, check the metadata reference.