Référence des données de route

L’objet de données de route de Starlight contient des informations sur la page courante. Apprenez-en plus sur le fonctionnement du modèle de données de Starlight dans le guide « Données de route ».

Dans les composants Astro, accédez aux données de route à partir de Astro.locals.starlightRoute :

src/components/Custom.astro

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

Dans un middleware de route, accédez aux données de route à partir de l’objet de contexte passé à votre fonction middleware :

src/routeData.ts

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

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

starlightRoute

L’objet starlightRoute contient les propriétés suivantes :

dir

Type : 'ltr' | 'rtl'

Le sens d’écriture de la page.

lang

Type : string

L’étiquette d’identification BCP-47 pour la langue de la page, par exemple en, zh-CN ou pt-BR.

locale

Type : string | undefined

Le chemin de base utilisé pour servir une langue. undefined pour les slugs de la locale racine.

siteTitle

Type : string

Le titre du site pour la langue de cette page.

siteTitleHref

Type : string

La valeur de l’attribut href du titre du site, renvoyant à la page d’accueil, par exemple /. Pour les sites multilingues, cette valeur inclura la locale actuelle, par exemple /fr/ ou /zh-cn/.

id

Type : string

Le slug de cette page.

isFallback

Type : boolean | undefined

true si cette page n’est pas traduite dans la langue actuelle et utilise le contenu de la langue par défaut en tant que repli. Utilisé uniquement dans les sites multilingues.

entryMeta

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

Métadonnées de la locale pour le contenu de la page. Peut être différent des valeurs de locale de premier niveau lorsque la page utilise un contenu de repli.

entry

L’entrée de la collection de contenu Astro pour la page courante. Inclut les valeurs du frontmatter pour la page courante dans entry.data.

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

Pour en savoir plus sur le format de cet objet, consultez la référence du type d’entrée de collection.

sidebar

Type : Array<SidebarLink | SidebarGroup>

Les entrées de la barre latérale de navigation du site pour cette page. Chaque entrée est soit un lien de barre latérale, soit un groupe de barre latérale.

Type SidebarLink

Les entrées de lien de la barre latérale représentent un lien affiché dans la barre latérale et possèdent les propriétés suivantes :

type

Type : 'link'

Le type identifiant cette entrée comme un lien de barre latérale.

label

Type : string

Le texte du lien.

href

Type : string

L’URL vers laquelle le lien pointe.

isCurrent

Type : boolean

true si le lien pointe vers la page actuelle.

attrs

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

Attributs HTML ajoutés à l’élément <a> rendu.

badge

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

Configuration du badge à afficher à côté du texte du lien, le cas échéant. Consultez la référence des props du composant <Badge> pour plus de détails.

autogenerate

Type : { directory: string } | undefined

Pour les liens créés à partir d’une entrée de barre latérale générée automatiquement, directory correspond à la valeur configurée pour autogenerate.directory.

Lorsque la barre latérale (sidebar) n’est pas configurée, Starlight génère des entrées pour toutes les pages de documentation et utilise une chaîne de caractères vide ('') comme valeur pour directory.

Type SidebarGroup

Les entrées de groupe de la barre latérale représentent un groupe de liens affichés dans la barre latérale et possèdent les propriétés suivantes :

type

Type : 'group'

Le type identifiant cette entrée comme un groupe de barre latérale.

label

Type : string

Le texte du groupe.

entries

Type : Array<SidebarLink | SidebarGroup>

Les entrées de barre latérale imbriquées dans ce groupe, qui peuvent être des liens ou des groupes.

collapsed

Type : boolean

Indique si le groupe est rétracté par défaut.

badge

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

Configuration du badge à afficher à côté du texte du groupe, le cas échéant. Consultez la référence des props du composant <Badge> pour plus de détails.

autogenerate

Type : { directory: string } | undefined

Pour les groupes créés à partir d’une entrée de barre latérale générée automatiquement, directory correspond à la valeur configurée pour autogenerate.directory.

Lorsque la barre latérale (sidebar) n’est pas configurée, Starlight génère des entrées pour toutes les pages de documentation et utilise une chaîne de caractères vide ('') comme valeur pour directory.

hasSidebar

Type : boolean

Indique si la barre latérale est affichée sur cette page.

pagination

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

Liens vers la page précédente et suivante dans la barre latérale si celle-ci est activée.

toc

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

Table des matières de la page courante si celle-ci est activée.

headings

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

Un tableau de toutes les en-têtes Markdown extraites de la page courante. Utilisez toc à la place si vous souhaitez construire un composant de table des matières qui respecte les options de configuration de Starlight.

lastUpdated

Type : Date | undefined

Un objet JavaScript de type Date représentant la date de dernière mise à jour de cette page si cette fonctionnalité est activée.

editUrl

Type : URL | undefined

Un objet URL de l’adresse où cette page peut être modifiée si cette fonctionnalité est activée.

head

Type : HeadConfig[]

Tableau de toutes les balises à inclure à l’intérieur de l’élément <head> de la page courante. Inclut des balises importantes comme <title> et <meta charset="utf-8">.

Utilitaires

defineRouteMiddleware()

Utilisez l’utilitaire defineRouteMiddleware() pour vous aider à typer votre module de middleware de route :

src/routeData.ts

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

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

Type StarlightRouteData

Si vous écrivez du code qui utilise les données de route de Starlight, vous pouvez importer le type StarlightRouteData qui correspond au format de Astro.locals.starlightRoute.

Dans l’exemple suivant, une fonction usePageTitleInTOC() met à jour les données de route pour utiliser le titre de la page courante comme libellé du premier élément de la table des matières, remplaçant le libellé par défaut « Sur cette page ». Le type StarlightRouteData vous permet de vérifier si les modifications des données de route sont valides.

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

Cette fonction peut ensuite être appelée à partir d’un middleware de route :

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