Starlight 0.35

🌟 Starlight 0.35 wants to be your summer icon with a release that makes customizing your docs easier than ever.

Let’s dive into the highlights from this release:

Custom icons in asides
Custom attributes for autogenerated sidebar links
Custom page slug processing

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

Custom icons in asides

Starlight’s asides make it easy to add styled notes, warnings, and other kinds of callouts to your docs pages. Starlight 0.35 takes this one step further, allowing you to override an aside’s icon.

Add an icon attribute to your aside to customize the icon, with support across Markdown, MDX, and Markdoc pages:

:::tip{icon="heart"}
Show your love with a heart icon.
:::

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" icon="heart">
  Show your love with a heart icon.
</Aside>

{% aside type="tip" icon="heart" %}
Show your love with a heart icon.
{% /aside %}

Currently, asides can be styled using Starlight’s built-in icons, but we’re planning to expand this to include custom icon support in a future release.

Thank you to Shubham Padia who contributed this feature!

Starlight 0.35 adds support for applying custom HTML attributes to all links in an autogenerated sidebar group. This makes it easier to add a custom style or behavior to all links in part of your sidebar.

Use the new autogenerate.attrs option in your sidebar configuration to add custom attributes. For example, you could decide to italicize all links in a specific autogenerated group:

starlight({
  title: 'My docs',
  sidebar: [
    {
      label: 'Constellations',
      autogenerate: {
        // Autogenerate a group of links for the 'constellations' directory.
        directory: 'constellations',
        // Italicize all link labels in this group.
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
}),

Custom page slug processing

It’s now easier to customize how your docs file names are mapped to URLs.

By default, Astro uses the popular github-slugger package to normalize content file names. For example, the content in Example.File.md is served at /examplefile. This ensures consistent output and URL compatibility with many common platforms.

However, if you need to customize this normalization, you can now pass a generateId option to Starlight’s docsLoader() in your content configuration. The following example avoids all normalization and just strips the file extensions from content files:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader({
      // Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
      generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
    }),
    schema: docsSchema(),
  }),
};

Bug fixes and more

As always, we’ve also been working to fix issues and extend existing features. The Starlight changelog lists all the details including migration guidance for breaking changes.

Here are a few of the bigger changes in 0.35:

Markdown plugins now limited to docs content

Markdown content outside of Starlight’s src/content/docs/ collection is no longer processed by Starlight’s default remark and rehype plugins. This improves compatibility with sites using Markdown content in non-Starlight pages.

If you were relying on the previous behavior, we’d love to hear from you! Please open a GitHub Discussion to let us know your use case.

Banner content is now excluded from search results

Content added using Starlight’s banner frontmatter property is no longer indexed by our default search provider Pagefind. This fixes some unexpected behavior in the search modal.