Starlight 0.39

Starlight is Astro’s official package for building fast, accessible documentation websites, with all the features you need built in.

Here’s what’s new in this release:

• More flexible autogenerated sidebar links
• Styling improvements
• Features for multilingual sites

To upgrade an existing Starlight site, use the automated @astrojs/upgrade CLI tool. This will update Starlight, Astro, and any other integrations you are using:

npx @astrojs/upgrade

See the Starlight CHANGELOG for migration guidance and full details of breaking changes.

Flexible sidebar autogeneration

Starlight has included support for generating sidebar navigation links from directories of content since day one. This release brings new flexibility to how this works.

Previously, autogeneration always created a labeled group in the sidebar for the specified directory. With v0.39, Starlight’s autogenerated links can be slotted alongside any other link types.

If you have existing autogenerated link groups in your sidebar, update them by wrapping the config in an items array:

starlight({
	sidebar: [
		{
			label: 'My group',
-			autogenerate: { directory: 'some-dir' },
+			items: [{ autogenerate: { directory: 'some-dir' } }],
		},
	],
	// ...
}),

This change makes it easy to combine autogeneration with different kinds of links. For example, you can now add one-off custom links alongside autogenerated ones. The following example groups a local page, all pages in the features directory, and an external link:

starlight({
	sidebar: [
		{
			label: 'Features',
			items: [
				// A page not in the features directory
				'features-overview',
				// All pages in the features directory
				{ autogenerate: { directory: 'features' } },
				// An external link
				{ label: 'Support', link: 'https://support.example.com' },
			],
		},
	],
	// ...
}),

Styling improvements

Modern CSS makes everyone’s lives easier by the day, and with this release we’re putting it to good use.

• We’ve improved spacing of nested lists in your content thanks to the magic of :has(). (Check out the full selector — it’s a doozy.)
• When users expand or collapse a sidebar group, causing overflow, the Starlight sidebar is now more stable. We banished layout shift with a simple scrollbar-gutter: stable.

Better multilingual sites

Starlight’s internationalization story has been key from the outset, and we’re always looking to push it forward. This release brings:

• Improved multilingual SEO with x-default meta links to pages in the site’s default locale. These alternate links are used by search engines as a signal of which language to fall back to if no other is available.
• Better text layout in Chinese and Japanese documentation thanks to the text-autospace CSS property. This newer CSS property makes text more legible by automatically applying spacing between CJK and non-CJK characters.
• We’ve updated i18next, the underlying library powering Starlight’s localization APIs, from v23 to v26.

Community

The Astro core team is:

Alexander Niebuhr, Armand Philippot, Chris Swithinbank, Emanuele Stoppa, Erika, Florian Lefebvre, Fred Schott, HiDeoo, Luiz Ferraz, Matt Kane, Matthew Phillips, Reuben Tier, Sarah Rainsberger, and Yan Thomas.

We look forward to seeing what you build with Starlight! If you have questions, comments, or just want to say hi, drop by the Astro Discord.