Mention how route data works on custom pages

[trueberryless]

Currently the route data guide does not mention how it works on custom pages using the <StarlightPage>. As far as I know, there shouldn't be any difference for the user, alto making this work internally took some time.

The custom pages guide also doesn't mention anything the other way around (how <StarlightPage> works together with route data).

I wonder if in one of the two places this should be mentioned or if this could maybe wait and sometime in the future we could think about adding a few "recipes" similar to the Astro docs in the "How-to guide" style from Diataxis? 🤔

Why is this necessary?

Explain how different concepts in Starlight work together and can be utilized to achieve advanced scenarios and opportunities.

[delucis]

As far as I know, there shouldn't be any difference for the user

Correct, StarlightPage adds route data so that everything inside it works as expected:

starlight/packages/starlight/components/StarlightPage.astro

Lines 11 to 14 in af61ee1

	await attachRouteDataAndRunMiddleware(
	Astro,
	await generateStarlightPageRouteData({ props: Astro.props, context: Astro })
	);

The only difference is that you can’t really use Astro.locals.starlightRoute in the file where you’re using <StarlightPage> because that’s running before the data is set up. But hopefully that’s reasonably clear, it would be surprising to expect something like this to work:

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';

// No way this `title` could already have the "My custom page" value set below
const { title } = Astro.locals.starlightRoute.entry.data;
---

<StarlightPage frontmatter={{ title: 'My custom page' }}>
  <!-- Custom page content -->
</StarlightPage>