Improve DX for sidebar prop in <StarlightPage> and document it

[delucis]

Description

This PR adds a parsing step to process the value of sidebar passed to <StarlightPage>. This allows us to improve DX by not requiring lots of boilerplate setting default values, for example:

Before

<StarlightPage
	sidebar={[
		{
			type: 'link',
			label: 'Custom link 1',
			href: '/test/1',
			isCurrent: false,
			badge: undefined,
			attrs: {},
		}
	]}
/>

After

<StarlightPage
	sidebar={[
		{ 
			label: 'Custom link 1',
			href: '/test/1',
		}
	]}
/>

Setting these extra props is still valid, but not required. type has been marked as @deprecated as it can be inferred so there is no real need to set it manually although you still can.

While working on this and the documentation, I realised we leaked a difference in naming between the internal SidebarEntry shape and the public sidebar config used in astro.config.mjs. In user config, link groups have an items array, whereas internally we named this entries. It’s probably a good idea to align these so that we have some consistency.

In this PR I’ve added support for setting items in link groups so we can document that. Setting entries instead is still also supported although it is marked as @deprecated to steer people away from it. In a future version we can start warning about use of entries, and later on remove support entirely. For now, I was aiming for full backwards compatibility so this can go out as a patch.

Aside: there’s a fair amount of fiddly Zod stuff to get this working — should get cleaner once we remove entries support.

[changeset-bot]

🦋 Changeset detected

Latest commit: 85d373b

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	Patch

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Feb 20, 2024 6:37pm

1 Ignored Deployment

Name	Status	Preview	Updated (UTC)
starlight-i18n	⬜️ Ignored (Inspect)		Feb 20, 2024 6:37pm

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	5.23 KB (0%)
/_astro/*.js	21.54 KB (0%)
/_astro/*.css	13.13 KB (0%)

[sarah11918]

Just a couple of quick comments from me!

[sarah11918]

The example is really explicit! Nicely done!

I am left wondering whether I can still do things like autogenerate here, though. If so, it might be nice to show another grouping where that happens? If not, a line mentioning that this config should manually list out the entire contents of the sidebar as autogeneration of groups is not available, or something like that, would be helpful!

[delucis]

Autogeneration is not supported here no — it’s really just what is shown! I’m actually torn about documenting that we don’t support it. Discussed a bit on Discord with @HiDeoo about the idea that it could be supported in theory. So I’d kind of like to avoid explicitly saying we don‘t as a fishing hook to see if we get feedback that people need/are trying to use it.

[HiDeoo]

Finally got the time to play more than a few minutes with the changes. In the end, pretty much of all the logic is in the Zod schema and I have to say, it works exactly like I expected after testing a few scenarios. 👍

I'm really happy with the result, way nicer API for users.

Unrelated note: I'd like at some point to see if we can slightly improve our Zod error map, specially around unions, it's not that great right now, but definitely in another PR.

[delucis]

I'm really happy with the result, way nicer API for users.

Yay!

Unrelated note: I'd like at some point to see if we can slightly improve our Zod error map, specially around unions, it's not that great right now, but definitely in another PR.

I actually have an old work-in-progress branch that made some improvements here and this work also reminded me of that. Will try to dust it off and share in case there’s something useful there.