Metadata

The Starlight Auto Sidebar plugin supports customizing autogenerated sidebar groups 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.

The following metadata file located in the src/content/docs/reference/api-reference/ directory customizes the api-reference directory when included in an autogenerated sidebar group:

src/content/docs/reference/api-reference/_meta.yml

# Metadata for the `api-reference` directory.

Note that having a metadata file in a directory that is not part of an autogenerated sidebar group will not have any effect on the sidebar.

Metadata properties

A metadata file accepts the following properties:

label

Type: string

Set the label of the directory containing the metadata file in the sidebar when displayed in an autogenerated sidebar group.

_meta.yml

# Set the directory sidebar label to `API Reference`.
label: API Reference

This property can only be used in nested directories of an autogenerated sidebar group. To customize the root directory label of an autogenerated sidebar group, use the label property in the autogenerated sidebar group configuration.

badge

Type: string | BadgeConfig

Add a badge to the directory containing the metadata file in the sidebar when displayed in an autogenerated sidebar group.

When using a string, the badge will be displayed with a default accent color. Optionally, pass a BadgeConfig object with text, variant, and class fields to customize the badge.

_meta.yml

# Add a badge to the directory sidebar label matching the default accent color.
badge: New

_meta.yml

# Add a caution badge to the directory sidebar label.
badge:
  text: Experimental
  variant: caution

This property can only be used in nested directories of an autogenerated sidebar group. To customize the root directory badge of an autogenerated sidebar group, use the badge property in the autogenerated sidebar group configuration.

collapsed

Type: boolean
Default: false

Define whether the directory containing the metadata file in the sidebar should be collapsed or not when displayed in an autogenerated sidebar group.

_meta.yml

# Collapse the directory in the sidebar.
collapsed: true

This property can only be used in nested directories of an autogenerated sidebar group. To customize if the root directory of an autogenerated sidebar group should be collapsed or not, use the collapsed property in the autogenerated sidebar group configuration.

order

Type: number

Control the order of the directory containing the metadata file when sorting an autogenerated group.

Lower numbers are displayed higher up in the group. This property will be used in addition to the Starlight order frontmatter field of a page to determine the order of items in the group.

_meta.yml

# Display this directory first in the sidebar group.
order: 1

sort

Type: 'slug' | 'reverse-slug'
Default: 'slug'

Control the sorting order of the content in the directory containing the metadata file.

By default, content in autogenerated sidebar groups is sorted by user-specific order or alphabetically by slug. Setting this property to 'reverse-slug' will sort the content in reverse alphabetical order by slug while preserving the user-specific order.

Pagination links are updated to reflect the sorting but still respect user-specific pagination links.

_meta.yml

# Reverse sort the content in the directory.
sort: reverse-slug

hidden

Type: boolean
Default: false

Prevents the directory containing the metadata file from being included in an autogenerated sidebar group.

_meta.yml

# Hide the directory from the sidebar.
hidden: true

depth

Type: number
Default: Infinity

Limit the depth of content in the directory containing the metadata file when displayed in an autogenerated sidebar group.

_meta.yml

# Hide any content deeper than 2 levels.
depth: 2

cascade

Type: ('collapsed' | 'sort')[]

Cascade some options of the directory containing the metadata file to all nested directories when displayed in an autogenerated sidebar group.

By default, options defined in a metadata file are only applied to the directory containing the metadata file. Defining some options for this property will apply them to all nested directories.

_meta.yml

# Collapse the directory in the sidebar.
collapsed: true
# Cascade the `collapsed` property to all nested directories.
cascade:
  - collapsed

To learn more about cascading metadata properties, check the “Cascading Metadata” guide.