Routendaten Referenz

Das Routendatenobjekt von Starlight enthält Informationen über die aktuelle Seite. Erfahre mehr darüber, wie das Datenmodell von Starlight funktioniert, in der „Routendaten“-Anleitung.

In Astro-Komponenten greifst du auf die Routendaten von Astro.locals.starlightRoute zu:

src/components/Custom.astro

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

In der Routen-Middleware greifst du auf die Routendaten aus dem Kontextobjekt zu, das an deine Middleware-Funktion übergeben wird:

src/routeData.ts

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

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

starlightRoute

Das Objekt starlightRoute hat die folgenden Eigenschaften:

dir

Typ: 'ltr' | 'rtl'

Schreibrichtung der Seite.

lang

Typ: string

BCP-47-Sprachkennzeichen für das Gebietsschema dieser Seite, z. B. de, zh-CN oder pt-BR.

locale

Typ: string | undefined

Der Basispfad, unter dem eine Sprache angeboten wird. undefined für Root-Locale-Slugs.

siteTitle

Typ: string

Der Seitentitel für das Gebietsschema dieser Seite.

siteTitleHref

Typ: string

Der Wert für das Attribut href des Seitentitels, der auf die Homepage zurückverweist, z. B. /. Bei mehrsprachigen Websites wird hier das aktuelle Gebietsschema angegeben, z. B. /en/ oder /zh-cn/.

id

Typ: string

Der Slug für diese Seite.

isFallback

Typ: boolean | undefined

true, wenn diese Seite in der aktuellen Sprache unübersetzt ist und Fallback-Inhalte aus dem Standardgebiets­schema verwendet. Wird nur in mehrsprachigen Websites verwendet.

entryMeta

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

Gebietsschema-Metadaten für den Seiteninhalt. Du kannst von den Werten der Top-Level-Locale unterscheiden, wenn eine Seite Fallback-Inhalte verwendet.

entry

Der Astro-Inhaltssammlungs­eintrag für die aktuelle Seite. Beinhaltet Frontmatter-Werte für die aktuelle Seite in entry.data.

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

Erfahre mehr über die Form dieses Objekts in der Astros Eintragstyp-Sammlung Referenz.

sidebar

Typ: Array<SidebarLink | SidebarGroup>

Seitennavigations­einträge für diese Seite. Jeder Eintrag ist entweder ein Seitenleisten-Link oder eine Seitenleisten-Gruppe.

SidebarLink-Typ

Einträge für Seitenleisten-Links sind Links, die in der Seitenleiste angezeigt werden, und weisen folgende Eigenschaften auf:

type

Typ: 'link'

Der Typ, der diesen Eintrag als Seitenleisten-Link kennzeichnet.

label

Typ: string

Die Bezeichnung des Links.

href

Typ: string

Die URL, auf die der Link verweist.

isCurrent

Typ: boolean

true, wenn der Link auf die aktuelle Seite verweist.

attrs

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

HTML-Attribute, die dem gerenderten <a>-Element hinzugefügt wurden.

badge

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

Konfiguration des Abzeichens, das gegebenenfalls neben der Link-Bezeichnung angezeigt wird. Weitere Informationen findest du in der Referenz zu den Eigenschaften der <Badge>-Komponente.

autogenerate

Typ: { directory: string } | undefined

Bei Links, die aus einem automatisch generierten Seitenleisten-Eintrag erstellt wurden, entspricht directory dem unter autogenerate.directory konfigurierten Wert.

Wenn die sidebar nicht konfiguriert ist, generiert Starlight Einträge für alle Dokumentations­seiten und verwendet eine leere Zeichenfolge ('') als Wert für directory.

SidebarGroup-Typ

Einträge in der Seitenleistengruppe stellen eine Gruppe von Links dar, die in der Seitenleiste angezeigt werden, und weisen folgende Eigenschaften auf:

type

Typ: 'group'

Der Typ, der diesen Eintrag als Seitenleistengruppe kennzeichnet.

label

Typ: string

Die Bezeichnung der Gruppe.

entries

Typ: Array<SidebarLink | SidebarGroup>

Die verschachtelten Einträge in der Seitenleiste innerhalb dieser Gruppe, bei denen es sich entweder um Links oder um Gruppen handeln kann.

collapsed

Typ: boolean

Ob die Gruppe standardmäßig ausgeblendet ist.

badge

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

Konfiguration des Abzeichens, das gegebenfalls neben der Gruppenbezeichnung angezeigt werden soll. Weitere Informationen findest du in der Referenz zu den Eigenschaften der <Badge>-Komponente.

autogenerate

Typ: { directory: string } | undefined

Bei Gruppen, die aus einem automatisch generierten Seitenleisten-Eintrag erstellt wurden, entspricht directory dem konfigurierten Wert für autogenerate.directory.

Wenn die sidebar nicht konfiguriert ist, generiert Starlight Einträge für alle Dokumentations­seiten und verwendet eine leere Zeichenfolge ('') als Wert für directory.

hasSidebar

Typ: boolean

Ob die Seitenleiste auf dieser Seite angezeigt werden soll oder nicht.

pagination

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

Links zur vorherigen und nächsten Seite in der Seitenleiste, falls aktiviert.

toc

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

Inhaltsverzeichnis für diese Seite, falls aktiviert.

headings

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

Array aller Markdown-Überschriften, die aus der aktuellen Seite extrahiert wurden. Verwende stattdessen toc, wenn du einen Inhaltsverzeichnis-Komponenten erstellen willst, welches die Konfigurations­optionen von Starlight berücksichtigt.

lastUpdated

Typ: Date | undefined

JavaScript Date Objekt, welches angibt, wann diese Seite zuletzt aktualisiert wurde, falls aktiviert.

editUrl

Typ: URL | undefined

URL-Objekt für die Adresse, unter der diese Seite bearbeitet werden kann, falls aktiviert.

head

Typ: HeadConfig[]

Array mit allen Tags, die in den <head> der aktuellen Seite aufgenommen werden sollen. Enthält wichtige Tags wie <title> und <meta charset="utf-8">.

Hilfsmittel

defineRouteMiddleware()

Verwende das Hilfsmethode defineRouteMiddleware(), um dein Route-Middleware-Modul zu definieren:

src/routeData.ts

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

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

StarlightRouteData-Typ

Wenn du Code schreibst, der mit den Routendaten von Starlight arbeiten muss, kannst du den Typ StarlightRouteData importieren, damit er der Form von Astro.locals.starlightRoute entspricht.

Im folgenden Beispiel aktualisiert die Funktion usePageTitleInTOC() die Routedaten so, dass der Titel der aktuellen Seite als Beschriftung für den ersten Eintrag im Inhaltsverzeichnis verwendet wird und die Standard­beschriftung „Übersicht“ ersetzt. Mit dem Typ StarlightRouteData kannst du prüfen, ob die Änderungen der Routendaten gültig sind.

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;
  }
}

Diese Funktion kann dann von einer Route Middleware aufgerufen werden:

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);
});