Skip to content
Starlight Auto Sidebar

Demo

The “Demo” group visible in the sidebar is an autogenerated group defined using the following configuration:

starlight({
  sidebar: [
    {
      label: 'Demo',
      autogenerate: { directory: 'demo' },
    },
  ],
})

The src/content/docs/demo/ directory contains the following files and directories:

  • Directorydocs
    • …
    • Directorydemo
      • Directoryapi
        • order.md
        • product.md
        • user.md
      • Directorychangelog
        • v1-0-0.md
        • v2-0-0.md
        • v3-0-0.md
      • overview.mdx
    • …

By default, the following sidebar group will be generated by Starlight:

The Starlight Auto Sidebar plugin is used to customize various aspects of autogenerated sidebar groups:

  1. Rename the changelog directory sidebar label to Release Notes
  2. Change the sorting order of the changelog directory to be reversed
  3. Rename the api directory sidebar label to API
  4. Add an Experimental caution badge to the api directory sidebar label
  5. Collapse the api directory in the sidebar

Steps

Here are all the steps to customize the autogenerated sidebar groups to match the rendered sidebar:

  1. Rename the changelog directory

    To rename the changelog directory sidebar label to Release Notes, a metadata file located in the src/content/docs/reference/changelog/ directory is used.

    The label property is used to set the new label:

    src/content/docs/reference/changelog/_meta.yml
    # Set the directory sidebar label to `Release Notes`.
    label: Release Notes

  2. Change the sorting order of the changelog directory

    By default, content in an autogenerated sidebar groups is sorted by a user-specified order defined in a frontmatter field or alphabetically by slug. For a directory containing release notes, it might be useful to reverse the sorting order so that the latest release notes are displayed first.

    To change the sorting order of the changelog directory, a metadata file located in the src/content/docs/reference/changelog/ directory is used. The sort property is used to control the sorting order of the content in the directory:

    src/content/docs/reference/changelog/_meta.yml
    # Reverse the sorting order of the directory content.
    sort: reverse-slug

  3. Rename the api directory

    To rename the api directory sidebar label to API, a metadata file located in the src/content/docs/reference/api/ directory is used.

    The label property is used to set the new label:

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

  4. Add an Experimental caution badge to the api directory

    To add an Experimental caution badge to the api directory sidebar label, a metadata file located in the src/content/docs/reference/api/ directory is used.

    The badge property is used to add a badge to the directory sidebar label:

    src/content/docs/reference/api/_meta.yml
    # Add a caution badge to the directory sidebar label.
    badge:
      text: Experimental
      variant: caution

  5. Collapse the api directory

    To collapse the api directory in the sidebar, a metadata file located in the src/content/docs/reference/api/ directory is used.

    The collapsed property is used to make the directory collapsed in the sidebar:

    src/content/docs/reference/api/_meta.yml
    # Collapse the directory in the sidebar.
    collapsed: true

Check out the metadata reference to learn more about all the available customization options.