Improve custom page injection

[HiDeoo]

What version of starlight are you using?

0.11.1

What is your idea?

Enable custom page injection while still being able to use the default generated route data.

Why is this feature necessary?

This discussion is a follow-up of #861.

An Astro integration injecting a custom route using injectRoute() cannot use Starlight design (e.g. by rendering <Page/>) while still being able to use some of the data generated by Starlight (e.g. the sidebar content).

Reusing the same data generated by Starlight is useful in some cases, for example starlight-openapi which injects new routes to render OpenAPI endpoints documentation but does not need to override the default sidebar content.

Various solutions have already been talked about:

• Exposing generateRouteData()
• Exposing a new component to create a page that would use by default the data generated by Starlight but still allow to override some of them through individual props
• A potential injectPage() API avalailable through a plugin hook

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Linking withastro/roadmap#688 here too as it’s kind of related.

[HiDeoo]

I have been trying out various approaches to this issue so posting an update with my findings so far.

We briefly mentioned the idea of exposing generateRouteData() but I personally think this is a bad idea which exposes too much of the internals and not the obvious way to do it in this specific case.

One thing I noticed, still in this specific context, is that from Props, the only thing missing when creating a new route is the sidebar/navigation data. Everything else is specific to the route being created and should be defined by the one creating the route.
Considering this, one potential suggestion could be to expose only getSidebar() and getPrevNextLinks() but I also think this is not the best approach. What if at some point we include more data that is not page specific in Props? We would have to expose more and more functions.

Considering this, I have been thinking about 2 approaches:

Note: all names are just for the sake of the example (and I could not find something I like which is properly describing what this does) and should be discussed if we go with one of these approaches.

A new component

A component like <PageWithGlobalRouteData/> that would accept the following Props:

type Props = Omit<PageProps, "sidebar" | "hasSidebar">;

This would be used like the existing <Page/> when creating a new route where most props will be passed down by the integration/plugin injecting the new route (like this is the case right now) and the sidebar, hasSidebar and pagination props would be generated by the component itself and then it would render the built-in <Page/> with the correct props.

---
const { pagination, ...props } = Astro.props;
const sidebar = getSidebar(Astro.url.pathname, props.locale);
---

<Page
	{...props}
	hasSidebar
	sidebar={sidebar}
	pagination={pagination ?? getPrevNextLinks(sidebar, config.pagination, props.entry.data)}
>
	<slot />
</Page>

If we were to add more data to Props in the future that is not page specific, we would need to update the component to handle it.

A new helper

A new exposed helper function like withGlobalRouteData() that would need to be called with a similar Props object as the one described above and would return the same object with the sidebar, hasSidebar and pagination props added.

The code would be pretty much identical to the one described above and an integration injecting a new route would call this before rendering the built-in <Page/> component.

Note: this could even exists with the component approach (but not exposed) and used in that component and internally too to ensure everything is always in-sync between the internals props and the exposed component.

Thoughts

So far I have not been able to find a better approach than these 2. I am still not sure if there is a better way to do this, if I am missing something obvious or if we should go with one of these approaches.

This is personally one of my main issue in Starlight at the moment that I would love to see properly solved so if anyone has any thoughts on this, please feel free to share them.

[HiDeoo]

For people interested, I've setup a pull request in #1175 for an attempt at implementing this feature, any feedback is welcome.

[HiDeoo]

Closing this feature request as the <StarlightPage> component addresses the described use case and is available since Starlight v0.19 🚀