Customize Starlight's route data in a Starlight plugin

Starlight plugins offer an easy-to-share and reusable way to customize and extend Starlight, the fully-featured documentation theme built on top of the Astro framework.

This guide will walk you through the process of customizing Starlight’s route data in a Starlight plugin, which is an object containing all the information used to render a page.

Prerequisites

You will need to have a Starlight plugin set up. If you don’t have one yet, you can follow the “How to create a Starlight plugin” note to create one or refer to the Starlight documentation for a complete reference.

Customize route data

To customize route data, route data middlewares can be used to modify the route data object before it is used to render a page. Starlight plugins can add route data middlewares by using the addRouteMiddleware() and providing the module specifier of a route data middleware to it.

Export a route data middleware

To export a route data middleware file from a Starlight plugin, you can add a new entry in the exports field of the plugin’s package.json file.

The following example adds a new entry point name ./middleware that points to a middleware.ts file in the plugin’s root directory:

{
  "name": "starlight-plugin-example",
  "version": "0.0.1",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": "./plugin.ts"
    ".": "./plugin.ts",
    "./middleware": "./middleware.ts"
  },
  "peerDependencies": {
    "@astrojs/starlight": ">=0.34"
  }
}

Add the route data middleware to the Starlight configuration

To reference the previously exported route data middleware file in the Starlight configuration, you can use the addRouteMiddleware() function provided in the config:setup Starlight plugin configuration setup function.

This function takes an object with an entrypoint property that references the route data middleware file to add as its first argument.

The following example uses the addRouteMiddleware() function to add a route data middleware that is exported from the starlight-plugin-example package:

import type { StarlightPlugin } from '@astrojs/starlight/types'

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ addRouteMiddleware }) {
        // Add plugin-specific route data middleware.
        addRouteMiddleware({
          entrypoint: 'starlight-plugin-example/middleware',
        })
      },
    },
  }
}

After creating the middleware.ts file in the plugin’s root directory, you can add the custom route data middleware logic to it.

To learn more about Starlight plugins, check out the “Starlight Plugins by Example” notebook for additional guides and examples.