Support _meta.yaml files in document directories for flexible sidebar configuration

[tolg]

What version of starlight are you using?

0.34.4

What is your idea?

Add support for _meta.yaml files in document directories that follow the exact same YAML syntax and structure as MD file frontmatter, enabling centralized sidebar configuration with custom directory titles, file ordering, and metadata management while reducing the need for frontmatter in individual MD files.

Why is this feature necessary?

Currently, Starlight's sidebar configuration is limited to either:

1. Hard-coding directory structure in astro.config.mjs
2. Using sidebar.order in individual MD files' frontmatter
3. Relying on alphabetical/numerical file naming conventions

This approach becomes cumbersome and inflexible for large documentation projects where teams need to:

Core Problems to Solve

• Customize directory titles in the sidebar (currently shows raw directory names)
• Control the order of directories and files without modifying main config
• Create nested groupings for better organization
• Hide specific files from the sidebar (like drafts, assets, etc.)
• Maintain configuration close to the content (not in a separate config file)
• Reduce frontmatter requirements - currently every MD file needs title in frontmatter

🚀 Target Benefits

For Large Documentation Projects:

• Organizations with extensive documentation need fine-grained control over sidebar structure
• Content teams can easily adjust organization without touching configuration files
• Developers can focus on writing content rather than managing frontmatter

For Content Teams:

• Non-technical writers can organize documentation without learning config syntax
• Centralized metadata management through _meta.yaml files
• Intuitive placement of configuration files alongside content

For Developer Experience:

• Configuration lives with the content, making it easier to maintain
• Uses familiar YAML syntax (same as MD frontmatter)
• Better IDE support for YAML files vs. JavaScript config

📋 Real-world Impact

This feature would transform how teams manage documentation:

• Legacy documentation without frontmatter can be easily integrated
• Content imported from other systems can be organized without manual frontmatter addition
• Multi-language documentation can have customized sidebar structure per locale
• Dynamic content projects benefit from configuration that lives with the content

The implementation aligns perfectly with Starlight's philosophy of being both powerful and easy to use - maintaining simplicity for small projects while providing the flexibility needed for enterprise-scale documentation.

Do you have examples of this feature in other projects?

• Docusaurus: Uses _meta.json files in document directories for sidebar configuration
• VuePress: Supports .vuepress/config.js with flexible sidebar configuration
• GitBook: Allows sidebar configuration through SUMMARY.md files in document directories

Participation

• I am willing to submit a pull request for this feature.

[HiDeoo]

Thanks for the feedback.

Such feature is currently available using a plugin available here.

You can find in the plugin documentation how to get started with it and all the metadata you can use.