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:

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.

The Astro core team is:

Alexander Niebuhr , Ben Holmes , Caleb Jasik , Chris Swithinbank , Emanuele Stoppa , Erika , Florian Lefebvre , Fred Schott , Fuzzy , HiDeoo , Luiz Ferraz , Matt Kane , Matthew Phillips , Nate Moore , Reuben Tier , Sarah Rainsberger , and Yan Thomas .

Thanks to everyone who contributed to our recent releases with PRs and reviews, including Alvin Bryan, Armand Philippot, Bohdan Khodakivskyi, Bugo, Carlos Jorge Rodriguez, Cyprien AVICO, DeaM8N, Eveeifyeve, Felix Schneider, FrostyBee, Happydev, heisenberg0924, Jose Sebastian, Josh Goldberg, Junseong Park, Kevin, Kian, liruifengv, Louis Escher, Malcolm Nihlén, Martin Trapp, MathiasBuus, Matouš Kučera, Nelson-5553, Nguyen Long Nhat, Niall O’Brien, pppwaw, randomguy-2650, Randy88-art, RealRed, Renildo Pereira, Saad Khan, Sgal Cheung, Shubham Padia, techfg, and Thomas Bonnet.

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.

推荐订阅源