Support component customisation

[delucis]

What kind of changes does this PR include?

• Changes to Starlight code

Description

• Closes Ability to customise Starlight’s components #415
• Refactors Starlight’s internal components to use a standardised prop type. Does this by pulling up some logic to a top-level “route data” object.
• Minimises the amount of data manipulation done in component code. This should hopefully help ensure user components receive data in a format they can use directly relatively easily without needing to duplicate any of our code.
• Support overriding default components via Starlight config (will use a Vite virtual module to do this — still in progress on my local branch)
• Support “slots” — spaces in the layout where no default component is rendered but users can add custom UI Cancelled for now after some discussion — let’s see if we can make an override-only system as nice as possible!
• Refactor a couple of our components so that the boundaries lie where users most likely will want/expect them.
• Docs!

Docs preview →

How will this feature work?

• There’s a new components option in Starlight config where users can provide a component to override one of Starlight’s built-in components in astro.config.mjs:

  starlight({
    title: 'Docs with component overrides',
    components: {
      SocialIcons: './src/overrides/MySocialLinks.astro',
    },
  })

• Components used to override a built-in component can import types to get type-safe props. These are consistent across all components available to override:

  ---
  import type { Props } from '@astrojs/starlight/props';
  
  const { editUrl } = Astro.props;
       // ^ (property) StarlightRouteData.editUrl: URL | undefined
  ---

• Components can import the default implementation if they want to just add some DOM alongside the existing UI:

  ---
  // src/overrides/MySocialLinks.astro
  import Default from '@astrojs/starlight/components/SocialIcons.astro';
  import type { Props } from '@astrojs/starlight/props';
  ---
  
  <Default {...Astro.props}><slot /></Default>
  <a href="mailto:[email protected]">E-mail</a>

  Most components don’t require <slot />, but some do, so I’m thinking this pattern should be what we document for consistency. <PageFrame /> uses named slots, which might need extra documentation. Looked at refactoring it to avoid using them, but I think it would lead to worse code structure.

[changeset-bot]

🦋 Changeset detected

Latest commit: 98b80e0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	98b80e0
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/65203a766f500d000899c396
😎 Deploy Preview	https://deploy-preview-709--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	9.51 KB (+1.02% 🔺)
/_astro/*.js	19.27 KB (+0.08% 🔺)
/_astro/*.css	9.63 KB (+0.77% 🔺)

[TheOtterlord]

can't wait to use this 🥳

[adambraimbridge]

uses named slots, which might need extra documentation.

Starlight is awesome, I'm rather enjoying it but still learning.

I'd love to see the documentation for overriding the PageFrame.astro component, specifically how to preserve the named header slot.

[adambraimbridge]

Update: I think I figured it out. Really loving Starlight :) <3

---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/PageFrame.astro';
import { Header } from 'virtual:starlight/components';
import { Sidebar } from 'virtual:starlight/components';
---

<Default {...Astro.props}>
  <Header slot="header" {...Astro.props} />
  <Sidebar slot="sidebar" {...Astro.props} />
  <slot />
</Default>