Ir al contenido

Referencia de los Datos de Ruta

El objeto de datos de ruta de Starlight contiene información sobre la página actual. Aprende más sobre cómo funciona el modelo de datos de Starlight en la guía de “Datos de Ruta”.

En los componentes de Astro, accede a los datos de ruta desde Astro.locals.starlightRoute:

src/components/Custom.astro
---
const { hasSidebar } = Astro.locals.starlightRoute;
---

En el middleware de ruta, accede a los datos de ruta desde el objeto de contexto pasado a tu función de middleware:

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
export const onRequest = defineRouteMiddleware((context) => {
const { hasSidebar } = context.locals.starlightRoute;
});

El objeto starlightRoute tiene las siguientes propiedades:

Tipo: 'ltr' | 'rtl'

Dirección de escritura de la página.

Tipo: string

Etiqueta de idioma BCP-47 para la configuración regional de esta página, por ejemplo, en, zh-CN o pt-BR.

Tipo: string | undefined

La ruta base en la que se sirve un idioma. undefined para los slugs de la configuración regional raíz.

Tipo: string

El título del sitio para la configuración regional de esta página.

Tipo: string

El valor para el atributo href del título del sitio, que enlaza de vuelta a la página de inicio, por ejemplo, /. Para sitios multilingües, esto incluirá la configuración regional actual, por ejemplo, /en/ o /zh-cn/.

Tipo: string

El slug para esta página.

Tipo: boolean | undefined

true si esta página no está traducida en el idioma actual y está utilizando contenido de respaldo de la configuración regional predeterminada. Solo se utiliza en sitios multilingües.

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

Metadatos de configuración regional para el contenido de la página. Puede ser diferente de los valores de configuración regional de nivel superior cuando una página está utilizando contenido de respaldo.

La entrada de la colección de contenido de Astro para la página actual. Incluye los valores del frontmatter para la página actual en entry.data.

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

Aprende más sobre la forma de este objeto en la referencia del Tipo de Entrada de Colección de Astro.

Tipo: `Array<SidebarLink | SidebarGroup>

Entradas de la barra lateral de navegación del sitio para esta página. Cada entrada es un enlace de la barra lateral o un grupo de la barra lateral.

Las entradas de enlaces de la barra lateral representan enlaces que se renderizan en la barra lateral y tienen las siguientes propiedades:

Tipo: 'link'

El tipo que identifica esta entrada como un enlace de la barra lateral.

Tipo: string

El texto del enlace.

Tipo: string

La URL a la que apunta el enlace.

Tipo: boolean

true si el enlace apunta a la página actual.

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

Atributos HTML añadidos al elemento <a> renderizado.

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

Configuración de la insignia que se renderiza junto a la etiqueta del enlace, si la hay. Consulta la referencia de propiedades del componente <Badge> para obtener más detalles.

Tipo: { directory: string } | undefined

Para los enlaces creados a partir de una entrada de la barra lateral generada automáticamente, directory coincide con el valor configurado en autogenerate.directory.

Cuando la sidebar no está configurada, Starlight genera entradas para todas las páginas de documentación y usa una cadena de texto vacía ('') como valor de directory.

Las entradas de grupo de la barra lateral representan un conjunto de enlaces que se renderizan en la barra lateral y tienen las siguientes propiedades:

Tipo: 'group'

El tipo que identifica esta entrada como un grupo de barra lateral.

Tipo: string

El texto del grupo.

Tipo: Array<SidebarLink | SidebarGroup>

Las entradas anidadas de la barra lateral de este grupo, que pueden ser enlaces o grupos.

Tipo: boolean

Si el grupo aparece oculto por defecto.

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

Configuración de la insignia que se renderiza junto a la etiqueta del grupo, si la hay. Consulta la referencia de propiedades del componente <Badge> para obtener más detalles.

Tipo: { directory: string } | undefined

Para los grupos creados a partir de una entrada de la barra lateral generada automáticamente, directory coincide con el valor configurado en autogenerate.directory.

Cuando la sidebar no está configurada, Starlight genera entradas para todas las páginas de documentación y usa una cadena de texto vacía ('') como valor de directory.

Tipo: boolean

Indica si la barra lateral debe mostrarse o no en esta página.

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

Enlaces a la página anterior y siguiente en la barra lateral si está habilitada.

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

Tabla de contenido para esta página si está habilitada.

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

Array de todos los encabezados de Markdown extraídos de la página actual. Utiliza toc en su lugar si deseas construir un componente de tabla de contenido que respete las opciones de configuración de Starlight.

Tipo: Date | undefined

Objeto Date de JavaScript que representa cuándo se actualizó por última vez esta página si está habilitado.

Tipo: URL | undefined

Objeto URL para la dirección donde se puede editar esta página si está habilitado.

tipo: HeadConfig[]

Array de todas las etiquetas para incluir en el <head> de la página actual. Incluye etiquetas importantes como <title> y <meta charset="utf-8">.

Utiliza la utilidad defineRouteMiddleware() para ayudar a tipar tu módulo de middleware de ruta:

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
export const onRequest = defineRouteMiddleware((context) => {
// ...
});

Si estás escribiendo código que necesita trabajar con los datos de ruta de Starlight, puedes importar el tipo StarlightRouteData para que coincida con la forma de Astro.locals.starlightRoute.

En el siguiente ejemplo, una función usePageTitleInTOC() actualiza los datos de ruta para utilizar el título de la página actual como etiqueta para el primer elemento de la tabla de contenido, reemplazando la etiqueta predeterminada “Overview”. El tipo StarlightRouteData te permite verificar si los cambios en los datos de ruta son válidos.

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

Esta función se puede llamar desde un middleware de ruta:

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