fix: doc schema extend

[HiDeoo]

Description

Temporary draft PR, do not merge.

See #3936 (comment) for context and conversations.

[changeset-bot]

🦋 Changeset detected

Latest commit: 2e10b97

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

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	2e10b97
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/6a4901d32afeb70008d5c842
😎 Deploy Preview	https://deploy-preview-4040--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
🤖 Make changes	Run an agent on this branch

---

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

[HiDeoo]

I spent many hours this week trying to find a more "built-in" approach to this solution, even dug into the Zod codebase, but in the end, I personally didn't find a more elegant way to handle this.

Considering this, I'm opening up this PR for review to see if anyone has any other ideas, discuss if we want to use this approach, etc. (but we still don't want to merge this PR if we go with this approach).

[delucis]

Thanks @HiDeoo! I also opened colinhacks/zod#6191 in case someone might have ideas/suggestions, but I have the feeling Zod is a) massively used and gets a lot of incoming questions and b) not super actively maintained, so not sure if we’ll ever get a response.

I’m torn — on the one hand this fixes the issue, but on the other it’s a headache to maintain. It might be good to figure out exactly which things it’s impossible to extend currently and decide if that behaviour is acceptable or not? There’s one side of me that thinks “extend is intended mainly to add properties or make them required, not to override things like built-in enums” (after all, the intent of the schema is to ensure user frontmatter produces data compatible with Starlight’s code and components, and adding e.g. a new value to the variant enum breaks that contract) but on the other hand I can understand the utility to a user of extending that when implementing CTAs that support more variants.

[HiDeoo]

I'm definitely also torn and that'a also why I tried to find a better solution. Like you said, it's annoying to maintain, I'm pretty sure it's not 100% perfect and we could probably get issues about edge cases in the future (altho I would expect them to be minimal).

Considering the use case is also understandable (while still niche), I wonder if I'm not tempted to say "let's try it" as a fix for extend, and if it ends up being a problem, we can restrict the use of extend in a v1 or major?

But if someone has a strong opinion about this, stronger than me, I think I would definitely be to go along with it.

[delucis]

Yeah, I’m OK with that. For code sanity it might be good to move the new code into a utility file so that schema.ts is still primarily concerned with the schema and not Zod internals but I can comment that on #3936.

[HiDeoo]

Perfect. Considering this, I'll now close this PR for now (and we still have it in GH if ever needed for reference or something).

[delucis]

Thanks again for figuring this out!