|
| 1 | +--- |
| 2 | +title: Route Data |
| 3 | +description: Learn how Starlight’s page data model is used to render your pages and how you can customize it. |
| 4 | +--- |
| 5 | + |
| 6 | +import { Steps } from '@astrojs/starlight/components'; |
| 7 | + |
| 8 | +When Starlight renders a page in your documentation, it first creates a route data object to represent what is on that page. |
| 9 | +This guide explains how route data is generated, how to use it, and how you can customize it to modify Starlight’s default behavior. |
| 10 | + |
| 11 | +See the [“Route Data Reference”](/reference/route-data/) for a full list of the available properties. |
| 12 | + |
| 13 | +## What is route data? |
| 14 | + |
| 15 | +Starlight route data is an object containing all the information required to render a single page. |
| 16 | +It includes information for the current page as well as data generated from your Starlight configuration. |
| 17 | + |
| 18 | +## Using route data |
| 19 | + |
| 20 | +All of Starlight’s components use route data to decide what to render for each page. |
| 21 | +For example, the [`siteTitle`](/reference/route-data/#sitetitle) string is used to display the site title and the [`sidebar`](/reference/route-data/#sidebar) array is used to render the global sidebar navigation. |
| 22 | + |
| 23 | +You can access this data from the `Astro.locals.starlightRoute` global in Astro components: |
| 24 | + |
| 25 | +```astro title="example.astro" {2} |
| 26 | +--- |
| 27 | +const { siteTitle } = Astro.locals.starlightRoute; |
| 28 | +--- |
| 29 | +
|
| 30 | +<p>The title of this site is “{siteTitle}”</p> |
| 31 | +``` |
| 32 | + |
| 33 | +This can be useful for example when building [component overrides](/guides/overriding-components/) to customize what you display. |
| 34 | + |
| 35 | +## Customizing route data |
| 36 | + |
| 37 | +Starlight’s route data works out of the box and does not require any configuration. |
| 38 | +However, for advanced use cases, you may want to customize route data for some or all pages to modify how your site displays. |
| 39 | + |
| 40 | +This is a similar concept to [component overrides](/guides/overriding-components/), but instead of modifying how Starlight renders your data, you modify the data Starlight renders. |
| 41 | + |
| 42 | +### When to customize route data |
| 43 | + |
| 44 | +Customizing route data can be useful when you want to modify how Starlight processes your data in a way not possible with existing configuration options. |
| 45 | + |
| 46 | +For example, you may want to filter sidebar items or customize titles for specific pages. |
| 47 | +Changes like this do not require modifying Starlight’s default components, only the data passed to those components. |
| 48 | + |
| 49 | +### How to customize route data |
| 50 | + |
| 51 | +You can customize route data using a special form of “middleware”. |
| 52 | +This is a function that is called every time Starlight renders a page and can modify values in the route data object. |
| 53 | + |
| 54 | +<Steps> |
| 55 | + |
| 56 | +1. Create a new file exporting an `onRequest` function using Starlight’s `defineRouteMiddleware()` utility: |
| 57 | + |
| 58 | + ```ts |
| 59 | + // src/routeData.ts |
| 60 | + import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; |
| 61 | + |
| 62 | + export const onRequest = defineRouteMiddleware(() => {}); |
| 63 | + ``` |
| 64 | + |
| 65 | +2. Tell Starlight where your route data middleware file is located in `astro.config.mjs`: |
| 66 | + |
| 67 | + ```js ins={9} |
| 68 | + // astro.config.mjs |
| 69 | + import { defineConfig } from 'astro/config'; |
| 70 | + import starlight from '@astrojs/starlight'; |
| 71 | + |
| 72 | + export default defineConfig({ |
| 73 | + integrations: [ |
| 74 | + starlight({ |
| 75 | + title: 'My delightful docs site', |
| 76 | + routeMiddleware: './src/routeData.ts', |
| 77 | + }), |
| 78 | + ], |
| 79 | + }); |
| 80 | + ``` |
| 81 | + |
| 82 | +3. Update your `onRequest` function to modify route data. |
| 83 | + |
| 84 | + The first argument your middleware will receive is [Astro’s `context` object](https://docs.astro.build/en/reference/api-reference/). |
| 85 | + This contains full information about the current page render, including the current URL and `locals`. |
| 86 | + |
| 87 | + In this example, we are going to make our docs more exciting by adding an exclamation mark to the end of every page’s title. |
| 88 | + |
| 89 | + ```ts |
| 90 | + // src/routeData.ts |
| 91 | + import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; |
| 92 | + |
| 93 | + export const onRequest = defineRouteMiddleware((context) => { |
| 94 | + // Get the content collection entry for this page. |
| 95 | + const { entry } = context.locals.starlightRoute; |
| 96 | + // Update the title to add an exclamation mark. |
| 97 | + entry.data.title = entry.data.title + '!'; |
| 98 | + }); |
| 99 | + ``` |
| 100 | + |
| 101 | +</Steps> |
| 102 | + |
| 103 | +#### Multiple route middleware |
| 104 | + |
| 105 | +Starlight also supports providing multiple middleware. |
| 106 | +Set `routeMiddleware` to an array of paths to add more than one middleware handler: |
| 107 | + |
| 108 | +```js {9} |
| 109 | +// astro.config.mjs |
| 110 | +import { defineConfig } from 'astro/config'; |
| 111 | +import starlight from '@astrojs/starlight'; |
| 112 | + |
| 113 | +export default defineConfig({ |
| 114 | + integrations: [ |
| 115 | + starlight({ |
| 116 | + title: 'My site with multiple middleware', |
| 117 | + routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'], |
| 118 | + }), |
| 119 | + ], |
| 120 | +}); |
| 121 | +``` |
| 122 | + |
| 123 | +#### Waiting for later route middleware |
| 124 | + |
| 125 | +To wait for middleware later in the stack to run before executing your code, you can await the `next()` callback passed as the second argument to your middleware function. |
| 126 | +This can be useful to wait for a plugin’s middleware to run before making changes for example. |
| 127 | + |
| 128 | +```ts "next" "await next();" |
| 129 | +// src/routeData.ts |
| 130 | +import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; |
| 131 | + |
| 132 | +export const onRequest = defineRouteMiddleware(async (context, next) => { |
| 133 | + // Wait for later middleware to run. |
| 134 | + await next(); |
| 135 | + // Modify route data. |
| 136 | + const { entry } = context.locals.starlightRoute; |
| 137 | + entry.data.title = entry.data.title + '!'; |
| 138 | +}); |
| 139 | +``` |
0 commit comments