Skip to content
Starlight

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

Section titled “starlightRoute”

The starlightRoute object has the following properties:

dir

Section titled “dir”

Type: 'ltr' | 'rtl'

Page writing direction.

lang

Section titled “lang”

Type: string

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

locale

Section titled “locale”

Type: string | undefined

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

siteTitle

Section titled “siteTitle”

Type: string

The site title for this page’s locale.

siteTitleHref

Section titled “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/.

slug

Section titled “slug”

Type: string

The slug for this page generated from the content filename.

This property is deprecated and will be removed in a future version of Starlight. Migrate to the new Content Layer API by using Starlight’s docsLoader and use the id property instead.

id

Section titled “id”

Type: string

The slug for this page or the unique ID for this page based on the content filename if using the legacy.collections flag.

isFallback

Section titled “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

Section titled “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

Section titled “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.

Section titled “sidebar”

Type: SidebarEntry[]

Site navigation sidebar entries for this page.

hasSidebar

Section titled “hasSidebar”

Type: boolean

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

pagination

Section titled “pagination”

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

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

toc

Section titled “toc”

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

Table of contents for this page if enabled.

headings

Section titled “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

Section titled “lastUpdated”

Type: Date | undefined

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

editUrl

Section titled “editUrl”

Type: URL | undefined

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

Section titled “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

Section titled “Utilities”

defineRouteMiddleware()

Section titled “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

Section titled “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);
});