Ir al contenido

Referencia de Configuración

Starlight es una integración construida sobre el framework Astro. Puedes configurar tu proyecto dentro del archivo de configuración astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'Mi encantador sitio de documentación',
}),
],
});

Puedes pasar las siguientes opciones a la integración starlight.

tipo: string | Record<string, string>

Establece el título de tu sitio web. Se utilizará en los metadatos y en el título de la pestaña del navegador.

El valor puede ser un string o para sitios multilingües, un objeto con valores para cada idioma diferente. Cuando se usa la forma de objeto, las claves deben ser etiquetas BCP-47 (por ejemplo, en, ar o zh-CN):

starlight({
title: {
es: 'Mi encantador sitio de documentación',
de: 'Meine bezaubernde Dokumentationsseite',
},
});

tipo: string

Establece la descripción de tu sitio web. Es usada en los metadatos compartidos con los motores de búsqueda en la etiqueta <meta name="description"> si no se establece description en el frontmatter de una página.

tipo: LogoConfig

Establece un logotipo para mostrarlo en la barra de navegación junto al título del sitio o en su lugar. Puedes establecer una única propiedad src o establecer fuentes de imagen separadas para light y dark.

starlight({
logo: {
src: './src/assets/mi-logo.svg',
},
});
type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
| { src: string }
| { light: string; dark: string }
);

tipo: false | { minHeadingLevel?: number; maxHeadingLevel?: number }
por defecto: { minHeadingLevel: 2, maxHeadingLevel: 3 }

Configura la tabla de contenidos que se muestra a la derecha de cada página. De forma predeterminada, los encabezados <h2> y <h3> se incluirán en esta tabla de contenidos.

tipo: { baseUrl: string }

Hablita “Editar los enlaces” de está página estableciendo la URL base que se debe usar. El enlace final será editLink.baseUrl + la ruta de la página actual. Por ejemplo, para habilitar la edición de páginas en el repositorio withastro/starlight en GitHub:

starlight({
editLink: {
baseUrl: 'https://github.com/withastro/starlight/edit/main/',
},
});

Con esta configuración, una página /introduction tendría un enlace de edición que apunta a https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md.

tipo: SidebarItem[]

Configura los elementos de navegación de la barra lateral de tu sitio.

Una barra lateral es un array de enlaces, grupos de enlaces y entradas generadas automáticamente. Los elementos de la barra lateral se definen usando una de las siguientes propiedades:

  • link — Un solo enlace a una URL específica, p. ej. '/home' o 'https://example.com'. Un enlace también debe tener una label.

  • slug — una referencia a una página interna, p. ej. 'guides/getting-started'. De forma predeterminada, se usará el título de la página enlazada como etiqueta.

  • items — Un array que contiene más enlaces de la barra lateral, subgrupos y entradas generadas automáticamente. Un grupo también debe tener una label.

  • autogenerate — Un objeto que especifica un directorio de tus documentos para generar automáticamente enlaces y subgrupos. Las entradas generadas automáticamente se pueden colocar en el array items de un grupo.

Los enlaces internos también se pueden especificar como una cadena en lugar de un objeto con una propiedad slug.

starlight({
sidebar: [
// Un solo elemento de enlace etiquetado como “Home”.
{ label: 'Home', link: '/' },
// Un grupo etiquetado como "Start Here" que contiene cuatro enlaces.
{
label: 'Start Here',
items: [
// Usando `slug` para enlaces internos.
{ slug: 'intro' },
{ slug: 'installation' },
// O usando la forma abreviada para enlaces internos.
'tutorial',
'next-steps',
],
},
// Un grupo que enlaza a todas las páginas del directorio de referencia.
{
label: 'Reference',
items: [{ autogenerate: { directory: 'reference' } }],
},
],
});

Los grupos de la barra lateral generados automáticamente se ordenan alfabéticamente por el nombre del archivo. Por ejemplo, una página generada a partir de astro.md aparecería por encima de la página starlight.md.

Los grupos de enlaces se expanden de forma predeterminada. Puedes cambiar este comportamiento estableciendo la propiedad collapsed de un grupo como true.

Los subgrupos generados automáticamente también están expandidos de forma predeterminada. Establece la propiedad autogenerate.collapsed para colapsarlos.

sidebar: [
// Un grupo colapsado de enlaces.
{
label: 'Collapsed Links',
collapsed: true,
items: ['intro', 'next-steps'],
},
// Un grupo expandido que contiene subgrupos generados automáticamente colapsados.
{
label: 'Reference',
items: [
{
autogenerate: {
directory: 'reference',
collapsed: true,
},
},
],
},
],

Si tu sitio es multilingüe, se considera que la label de cada elemento está en el idioma predeterminado. Puedes establecer una propiedad de translations para proporcionar etiquetas en los otros idiomas que tu sitio admita:

sidebar: [
// Un ejemplo de barra lateral con etiquetas traducidas al portugués de Brasil.
{
label: 'Start Here',
translations: { 'pt-BR': 'Comece Aqui' },
items: [
{
label: 'Getting Started',
translations: { 'pt-BR': 'Introdução' },
link: '/getting-started',
},
{
label: 'Project Structure',
translations: { 'pt-BR': 'Estrutura de Projetos' },
link: '/structure',
},
],
},
],
type SidebarItem =
| string
| ({
translations?: Record<string, string>;
badge?: string | BadgeConfig;
} & (
| {
// Enlace
link: string;
label: string;
attrs?: Record<string, string | number | boolean | undefined>;
}
| {
// Enlace interno
slug: string;
label?: string;
attrs?: Record<string, string | number | boolean | undefined>;
}
| {
// Grupo de enlaces
label: string;
items: SidebarItem[];
collapsed?: boolean;
}
))
| {
// Enlaces y subgrupos generados automáticamente
autogenerate: {
directory: string;
collapsed?: boolean;
attrs?: Record<string, string | number | boolean | undefined>;
};
};
interface BadgeConfig {
text: string;
variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
class?: string;
}

tipo: { [dir: string]: LocaleConfig }

Configura la internacionalización (i18n) para tu sitio estableciendo qué locales se admiten.

Cada entrada debe usar el directorio donde se guardan los archivos de ese idioma como clave.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My Site',
// Establece el inglés como el idioma predeterminado para este sitio.
defaultLocale: 'en',
locales: {
// Los documentos en inglés en `src/content/docs/en/`
en: {
label: 'English',
},
// Los documentos en chino simplificado en `src/content/docs/zh-cn/`
'zh-cn': {
label: '简体中文',
lang: 'zh-CN',
},
// Los documentos en árabe en `src/content/docs/ar/`
ar: {
label: 'العربية',
dir: 'rtl',
},
},
}),
],
});
interface LocaleConfig {
label: string;
lang?: string;
dir?: 'ltr' | 'rtl';
}

Puedes establecer las siguientes opciones para cada idioma:

tipo: string

La etiqueta para este idioma que se muestra a los usuarios, por ejemplo, en el selector de idioma. Lo más probable es que quieras que este sea el nombre del idioma como un usuario de ese idioma esperaría leerlo, por ejemplo, "English", "العربية" o "简体中文".

tipo: string

La etiqueta BCP-47 para este lenguaje, por ejemplo, "en", "ar" o "zh-CN". Si no se establece, se utilizará el nombre del directorio del idioma de forma predeterminada. Las etiquetas de idioma con subetiquetas regionales (por ejemplo, "pt-BR" o "en-US") utilizarán las traducciones de la interfaz de usuario integradas para su idioma base si no se encuentran traducciones específicas de la región.

tipo: 'ltr' | 'rtl'

La dirección de escritura de este idioma; "ltr" para de izquierda a derecha (el valor predeterminado) o "rtl" para de derecha a izquierda.

Puedes servir el idioma predeterminado sin un directorio /lang/ estableciendo un idioma root:

starlight({
locales: {
root: {
label: 'English',
lang: 'en',
},
fr: {
label: 'Français',
},
},
});

Por ejemplo, esto te permite servir /getting-started/ como una ruta en inglés y usar /fr/getting-started/ como la página francesa equivalente.

tipo: string

Establece el idioma que es el predeterminado para este sitio. Este valor debe coincidir con una de las claves de tu objeto locales. (Si tu idioma predeterminado es tu idioma raíz, puedes omitir esto.)

El idioma predeterminado se utilizará para proporcionar contenido de respaldo donde faltan las traducciones.

tipo: Array<{ label: string; icon: StarlightIcon; href: string }>

Detalles opcionales sobre las cuentas de redes sociales para este sitio. Agregar cualquiera de estos los mostrará como enlaces de iconos en el encabezado del sitio.

starlight({
social: [
{ icon: 'codeberg', label: 'Codeberg', href: 'https://codeberg.org/knut' },
{ icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro' },
{ icon: 'gitlab', label: 'GitLab', href: 'https://gitlab.com/delucis' },
{ icon: 'mastodon', label: 'Mastodon', href: 'https://m.webtoo.ls/@astro' },
],
}),

tipo: string[]

Proporciona archivos CSS para personalizar el aspecto y la sensación de tu sitio Starlight.

Admite archivos CSS locales relativos a la raíz de tu proyecto, por ejemplo, './src/custom.css', y CSS que instalaste como un módulo npm, por ejemplo, '@fontsource/roboto'.

starlight({
customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});

tipo: { headingLinks?: boolean; processedDirs?: string[] }
por defecto: { headingLinks: true, processedDirs: [] }

Configura el procesamiento de Markdown de Starlight.

tipo: boolean
por defecto: true

Determina si los encabezados se renderizan con un enlace en el que se puede hacer clic.

starlight({
markdown: {
// Deshabilita los enlaces de los encabezados de Starlight en los que se puede hacer clic.
headingLinks: false,
},
}),

tipo: string[]
por defecto: []

Define directorios adicionales en los que Starlight debe procesar los archivos mediante su proceso de Markdown. Por defecto, solo se procesa el contenido Markdown y MDX cargado mediante la función docsLoader() de Starlight. Admite directorios locales relativos a la raíz de tu proyecto, p. ej., './src/data/comments/'.

El procesamiento de Starlight incluye compatibilidad con enlaces en los encabezados en los que se puede hacer clic, la sintaxis de la directiva de apartados de Markdown y compatibilidad con la escritura de derecha a izquierda (RTL) para los bloques de código. Esta opción puede resultar útil si estás renderizando contenido de una colección de contenido personalizada en una página personalizada utilizando el componente <StarlightPage> y deseas que el procesamiento de Markdown de Starlight se aplique también a ese contenido.

starlight({
markdown: {
// Procesar los archivos Markdown de la colección de contenidos `reviews` ubicada en el
// directorio `src/data/reviews/`.
processedDirs: ['./src/data/reviews/'],
},
}),

tipo: StarlightExpressiveCodeOptions | boolean
por defecto: true

Starlight usa Expressive Code para renderizar bloques de código y agregar soporte para resaltar partes de ejemplos de código, agregar nombres de archivo a bloques de código y más. Consulta la guía de “Bloques de código” para aprender a usar la sintaxis de Expressive Code en tu contenido Markdown y MDX.

Puedes usar cualquier de las opciones de configuración estándar de Expressive Code así como algunas propiedades específicas de Starlight, estableciéndolas en la opción expressiveCode de Starlight. Por ejemplo, establece la opción styleOverrides de Expressive Code para anular el CSS predeterminado. Esto permite personalizaciones como darle a tus bloques de código esquinas redondeadas:

starlight({
expressiveCode: {
styleOverrides: { borderRadius: '0.5rem' },
},
});

Si quieres deshabilitar Expressive Code, establece expressiveCode: false en tu configuración de Starlight:

starlight({
expressiveCode: false,
});

Adicionalmente a las opciones estándar de Expressive Code, también puedes establecer las siguientes propiedades específicas de Starlight en tu configuración expressiveCode para personalizar aún más el comportamiento del tema para tus bloques de código:

tipo: Array<string | ThemeObject | ExpressiveCodeTheme>
por defecto: ['starlight-dark', 'starlight-light']

Establece los temas utilizados para dar estilo a los bloques de código. Consulta la documentación de themes de Expressive Code para obtener detalles de los formatos de tema admitidos.

Starlight usa por defecto las variantes oscura y clara del tema Night Owl de Sarah Drasner.

Si proporcionas por lo menos un tema oscuro y uno claro, Starlight mantendrá automáticamente el tema de bloque de código activo sincronizado con el tema actual del sitio. Configura este comportamiento con la opción useStarlightDarkModeSwitch.

tipo: boolean
por defecto: true

Cuando sea true, los bloques de código cambian automáticamente entre temas claros y oscuros cuando cambia el tema del sitio. Cuando sea false, debes agregar manualmente CSS para manejar el cambio entre múltiples temas.

tipo: boolean
por defecto: true si themes no está establecido, de lo contrario false

Cuando sea true, se utilizan las variables CSS de Starlight para los colores de los elementos de la UI del bloque de código (fondos, botones, sombras, etc.), coincidiendo con el tema de color del sitio. Cuando sea false, se utilizan los colores proporcionados por el tema de resaltado de sintaxis activo para estos elementos.

tipo: boolean | PagefindOptions
por defecto: true

Configura Pagefind, el proveedor de búsqueda predeterminado de Starlight para tu sitio.

Establécelo en false para deshabilitar la indexación de tu sitio con Pagefind. Esto también ocultará la interfaz de búsqueda predeterminada si se está usando.

Pagefind no se puede habilitar cuando la opción prerender está establecida en false.

Establece pagefind como un objeto para configurar el cliente de búsqueda de Pagefind:

  • Consulta “Personalizar el ranking de resultados de Pagefind” en la documentación de Pagefind para obtener más detalles sobre cómo usar la opción pagefind.ranking para controlar cómo se calcula el ranking de los resultados de búsqueda.
  • Consulta “Buscar en varios sitios” en la documentación de Pagefind para obtener más detalles sobre cómo usar la opción pagefind.mergeIndex para controlar cómo buscar en varios sitios.
interface PagefindOptions {
ranking?: PagefindRankingOptions;
indexWeight?: number;
mergeIndex?: Array<{
bundlePath: string;
indexWeight?: number;
basePath?: string;
baseUrl?: string;
mergeFilter?: Record<string, string | string[]>;
language?: string;
ranking?: PagefindRankingOptions;
}>;
}
interface PagefindRankingOptions {
pageLength?: number;
termFrequency?: number;
termSaturation?: number;
termSimilarity?: number;
diacriticSimilarity?: number;
metaWeights?: Record<string, number>;
}

tipo: boolean
por defecto: true

Define si las páginas de Starlight deben ser pre-renderizadas a HTML estático o renderizadas bajo demanda por un adaptador SSR.

Las páginas de Starlight se pre-renderizan de forma predeterminada. Si estás usando un adaptador SSR y deseas renderizar las páginas de Starlight bajo demanda, establece prerender: false.

tipo: HeadConfig[]

Agrega etiquetas personalizadas a la etiqueta <head> de tu sitio Starlight. Puede ser útil para agregar análisis y otros scripts y recursos de terceros.

starlight({
head: [
// Ejemplo: agregar etiqueta de script de análisis de Fathom.
{
tag: 'script',
attrs: {
src: 'https://cdn.usefathom.com/script.js',
'data-site': 'MY-FATHOM-ID',
defer: true,
},
},
],
});

Las entradas en el head son convertidas directamente a elementos HTML y no pasan por el procesamiento de script o estilo de Astro. Si necesitas importar activos locales como scripts, estilos o imágenes, anula el componente Head.

interface HeadConfig {
tag: string;
attrs?: Record<string, string | boolean | undefined>;
content?: string;
}

tipo: boolean
por defecto: false

Controla si se muestra el pie de página que indica cuándo se actualizó por última vez la página.

De forma predeterminada, esta función se basa en el historial Git de tu repositorio y puede no ser precisa en algunas plataformas de implementación que realizan copias superficiales. Una página puede anular esta configuración o la fecha basada en Git utilizando el campo lastUpdated en el frontmatter.

tipo: boolean
por defecto: true

Define si el pie de página debe incluir enlaces a la página anterior y siguiente.

Una página puede anular esta configuración o el texto del enlace y/o la URL utilizando los campos de metadatos prev y next.

tipo: string
por defecto: '/favicon.svg'

Establece la ruta del favicon predeterminado para tu sitio web, el cual debería ubicarse en el directorio public/ y ser un archivo de icono válido (.ico, .gif, .jpg, .png o .svg).

starlight({
favicon: '/images/favicon.svg',
}),

Si necesitas establecer variantes adicionales o favicons de respaldo, puedes agregar etiquetas utilizando la opción head:

starlight({
favicon: '/images/favicon.svg',
head: [
// Agregar un favicon ICO de respaldo para Safari.
{
tag: 'link',
attrs: {
rel: 'icon',
href: '/images/favicon.ico',
sizes: '32x32',
},
},
],
});

tipo: string
por defecto: '|'

Establece un delimitador entre el título de la página y el título del sitio web en la etiqueta <title>, que se muestra en las pestañas del navegador.

Por defecto, cada página tiene un <title> de Título de la página | Título del sitio web. Por ejemplo, esta página es titulada “Referencia de Configuración” y este sitio web es titulado “Starlight”, por lo que el <title> de esta página es “Referencia de Configuración | Starlight”.

tipo: boolean
por defecto: false

Deshabilita la inyección de la página 404 predeterminada de Starlight. Para usar una ruta src/pages/404.astro personalizada en tu proyecto, establece esta opción en true.

tipo: string | string[]

Proporciona las rutas a middleware de ruta que puede modificar cómo Starlight procesa tus datos. Estas rutas de archivo no deben entrar en conflicto con el middleware de Astro.

Consulta la guía de datos de ruta para obtener detalles sobre cómo crear un middleware de ruta.

tipo: Record<string, string>

Proporciona las rutas a los componentes para sobreescribir las implementaciones predeterminadas de Starlight.

starlight({
components: {
SocialLinks: './src/components/MySocialLinks.astro',
},
});

Consulta la Referencia de Personalización de Componentes para obtener detalles de todos los componentes que puedes anular.

tipo: StarlightPlugin[]

Extiende Starlight con plugins personalizados. Los plugins aplican cambios a tu proyecto para modificar o agregar a las funcionalidades a Starlight.

Visita la exhibición de plugins para ver una lista de los plugins disponibles.

starlight({
plugins: [starlightPlugin()],
});

Consulta la Referencia de Plugins para obtener detalles sobre cómo crear tus propios plugins.

tipo: boolean
por defecto: false

Habilita la visualización de un enlace “Hecho con Starlight” en el pie de página de tu sitio.

starlight({
credits: true,
});

Starlight usa las colecciones de contenido de Astro para cargar tu contenido. Los loaders y esquemas de contenido de Starlight ayudan a configurar las colecciones según sea necesario.

src/content.config.ts
import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
// Opcional: la colección i18n se usa para traducir la interfaz en sitios multilingües
i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

Starlight exporta los siguientes loaders de Astro desde el módulo @astrojs/starlight/loaders para simplificar la configuración de las colecciones de contenido.

El docsLoader() carga archivos locales de Markdown, MDX y Markdoc desde el directorio src/content/docs/. Se ignoran los nombres de archivo que comienzan con un guion bajo (_).

import { docsLoader } from '@astrojs/starlight/loaders';

tipo: ({ entry: string; base: URL; data: Record<string, unknown> }) => string

Por defecto, las páginas generadas con docsLoader() procesan los nombres de tus archivos usando un sluggifier, que elimina los caracteres especiales y convierte el nombre del archivo a minúsculas. Si quieres anular este comportamiento, proporciona tu propia función generateId().

Por ejemplo, esto puede ser útil para conservar caracteres especiales que de otro modo se eliminarían. Por defecto, Example.File.md se serviría en /examplefile. Si quisieras servirlo en /Example.File, podrías hacerlo definiendo una función generateId() personalizada:

docsLoader({
// Elimina la extensión `.md` o `.mdx`, pero por lo demás no procesa los nombres de archivo.
generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),

Consulta generateId() en la documentación de Astro para obtener más detalles.

El i18nLoader() carga archivos locales JSON y YAML desde el directorio src/content/i18n/. Se ignoran los nombres de archivo que comienzan con un guion bajo (_).

import { i18nLoader } from '@astrojs/starlight/loaders';

Actualmente no hay opciones para configurar i18nLoader().

Starlight proporciona los siguientes esquemas de colecciones de contenido desde el módulo @astrojs/starlight/schema. Estos esquemas deben usarse para las colecciones docs e i18n de las que depende Starlight.

El docsSchema() analiza el frontmatter de todo tu contenido en la colección docs.

import { docsSchema } from '@astrojs/starlight/schema';

tipo: esquema de Zod o función que devuelve un esquema de Zod
por defecto: z.object({})

Extiende el esquema de frontmatter de Starlight con campos adicionales. Consulta “Personaliza el esquema del frontmatter” para obtener más detalles sobre cómo usar la opción extend.

El i18nSchema() analiza todos los archivos de datos de la colección i18n.

import { i18nSchema } from '@astrojs/starlight/schema';

tipo: objeto de Zod
por defecto: z.object({})

Extiende el esquema i18n de Starlight con campos adicionales. Consulta “Extiende el esquema de traducción” para obtener más detalles sobre cómo usar la opción extend.