Skip to content
Starlight Auto Sidebar

Using Metadata

Customizing autogenerated sidebar groups with the Starlight Auto Sidebar plugin is possible using metadata files.

Metadata files are named _meta.yml or _meta.yaml and are located at the root of an autogenerated sidebar group directory or in any subdirectory within the group that you want to customize.

Customize a directory

To customize a directory in an autogenerated sidebar group, create a metadata file named _meta.yml in any directory within the 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
        • Directoryadmin
          • 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

The updated sidebar will now look like this:

To also customize the admin directory label, create another metadata file named _meta.yml in the src/content/docs/reference/api-reference/admin/ directory with the following content:

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

The updated sidebar will now look like this:

By default, all properties in the metadata file apply only to the directory containing the metadata file. If you want to apply some properties to nested directories, you can use the cascade property.

To learn more about all the available properties, check the metadata reference.