Route Data Reference

Starlight’s route data object contains information about the current page. Learn more about how Starlight’s data model works in the “Route Data” guide.

In Astro components, access route data from Astro.locals.starlightRoute:

src/components/Custom.astro

---
const { hasSidebar } = Astro.locals.starlightRoute;
---

In route middleware, access route data from the context object passed to your middleware function:

src/routeData.ts

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  const { hasSidebar } = context.locals.starlightRoute;
});

starlightRoute

The starlightRoute object has the following properties:

dir

Type: 'ltr' | 'rtl'

Page writing direction.

lang

Type: string

BCP-47 language tag for this page’s locale, e.g. en, zh-CN, or pt-BR.

locale

Type: string | undefined

The base path at which a language is served. undefined for root locale slugs.

siteTitle

Type: string

The site title for this page’s locale.

siteTitleHref

Type: string

The value for the site title’s href attribute, linking back to the homepage, e.g. /. For multilingual sites this will include the current locale, e.g. /en/ or /zh-cn/.

id

Type: string

The slug for this page.

isFallback

Type: boolean | undefined

true if this page is untranslated in the current language and using fallback content from the default locale. Only used in multilingual sites.

entryMeta

Type: { dir: 'ltr' | 'rtl'; lang: string }

Locale metadata for the page content. Can be different from top-level locale values when a page is using fallback content.

entry

The Astro content collection entry for the current page. Includes frontmatter values for the current page at entry.data.

entry: {
  data: {
    title: string;
    description: string | undefined;
    // etc.
  }
}

Learn more about the shape of this object in Astro’s Collection Entry Type reference.

sidebar

Type: Array<SidebarLink | SidebarGroup>

Site navigation sidebar entries for this page. Each entry is either a sidebar link or a sidebar group.

SidebarLink type

Sidebar link entries represent a link rendered in the sidebar and have the following properties:

type

Type: 'link'

The type identifying this entry as a sidebar link.

label

Type: string

The text of the link.

href

Type: string

The URL that the link points to.

isCurrent

Type: boolean

true if the link points to the current page.

attrs

Type: Record<string, string | number | boolean | undefined>

HTML attributes added to the rendered <a> element.

badge

Type: { text: string; variant: 'note' | 'danger' | 'success' | 'caution' | 'tip' | 'default'; class?: string } | undefined

Badge configuration to render next to the link label, if any. See the <Badge> component props reference for details.

autogenerate

Type: { directory: string } | undefined

For links created from an autogenerated sidebar entry, directory matches the configured autogenerate.directory value.

When the sidebar is not configured, Starlight generates entries for all documentation pages and uses an empty string ('') as the directory value.

SidebarGroup type

Sidebar group entries represent a group of links rendered in the sidebar and have the following properties:

type

Type: 'group'

The type identifying this entry as a sidebar group.

label

Type: string

The text of the group.

entries

Type: Array<SidebarLink | SidebarGroup>

The nested sidebar entries within this group, which can be either links or groups.

collapsed

Type: boolean

Whether the group is collapsed by default.

badge

Type: { text: string; variant: 'note' | 'danger' | 'success' | 'caution' | 'tip' | 'default'; class?: string } | undefined

Badge configuration to render next to the group label, if any. See the <Badge> component props reference for details.

autogenerate

Type: { directory: string } | undefined

For groups created from an autogenerated sidebar entry, directory matches the configured autogenerate.directory value.

When the sidebar is not configured, Starlight generates entries for all documentation pages and uses an empty string ('') as the directory value.

hasSidebar

Type: boolean

Whether or not the sidebar should be displayed on this page.

pagination

Type: { prev?: Link; next?: Link }

Links to the previous and next page in the sidebar if enabled.

toc

Type: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined

Table of contents for this page if enabled.

headings

Type: { depth: number; slug: string; text: string }[]

Array of all Markdown headings extracted from the current page. Use toc instead if you want to build a table of contents component that respects Starlight’s configuration options.

lastUpdated

Type: Date | undefined

JavaScript Date object representing when this page was last updated if enabled.

editUrl

Type: URL | undefined

URL object for the address where this page can be edited if enabled.

head

type: HeadConfig[]

Array of all tags to include in the <head> of the current page. Includes important tags such as <title> and <meta charset="utf-8">.

Utilities

defineRouteMiddleware()

Use the defineRouteMiddleware() utility to help type your route middleware module:

src/routeData.ts

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
  // ...
});

StarlightRouteData type

If you are writing code that needs to work with Starlight’s route data, you can import the StarlightRouteData type to match the shape of Astro.locals.starlightRoute.

In the following example, a usePageTitleInTOC() function updates route data to use the current page’s title as the label for the first item in the table of contents, replacing the default “Overview” label. The StarlightRouteData type allows you to check whether the route data changes are valid.

src/route-utils.ts

import type { StarlightRouteData } from '@astrojs/starlight/route-data';

export function usePageTitleInTOC(starlightRoute: StarlightRouteData) {
  const overviewLink = starlightRoute.toc?.items[0];
  if (overviewLink) {
    overviewLink.text = starlightRoute.entry.data.title;
  }
}

This function can then be called from a route middleware:

src/route-middleware.ts

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
import { usePageTitleInTOC } from './route-utils';

export const onRequest = defineRouteMiddleware((context) => {
  usePageTitleInTOC(context.locals.starlightRoute);
});