Skip to content
Starlight Auto Sidebar

Cascading Metadata

By default, all properties in a metadata file apply only to the directory containing the metadata file. Cascading metadata allows you to apply some properties to nested directories when displayed in an autogenerated sidebar group.

Cascade metadata

To cascade some properties to nested directories, use the cascade property in the metadata file and specify the properties you want to apply to all nested directories.

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

  • Directorydocs
    • Directoryguides
      • example.md
    • Directoryreference
      • about.md
      • Directoryapi-reference
        • api.md
        • Directoryadmin
          • api.md
      • Directorychangelog
        • 2025.md
        • 2024.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 collapse the api-reference directory, 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
# Collapse the directory in the sidebar.
collapsed: true

The updated sidebar will now look like this:

If you expand the api-reference directory, you can notice that the admin directory is not collapsed. This is expected as properties in a metadata file apply only to the directory containing the metadata file by default.

To also collapse the admin directory, you can cascade the collapsed property to all nested directories using the cascade property in the same metadata file:

src/content/docs/reference/api-reference/_meta.yml
# Collapse the directory in the sidebar.
collapsed: true
# Cascade the `collapsed` property to all nested directories.
cascade:
  - collapsed

The updated sidebar will now look like this:

When expanding the api-reference directory, you can see that the admin directory is now collapsed as well.

To learn more about all the available properties that can be cascaded to nested directories, check the metadata reference.