Barra Lateral de Navegación
Una barra lateral bien organizada es clave para una buena documentación, ya que es una de las principales formas en que los usuarios navegarán por su sitio. Starlight proporciona un conjunto completo de opciones para personalizar el diseño y el contenido de tu barra lateral.
Barra lateral predeterminada
Por defecto, Starlight generará automáticamente una barra lateral basada en la estructura del sistema de archivos de tu documentación, utilizando la propiedad title
de cada archivo como entrada de la barra lateral.
Por ejemplo, dada la siguiente estructura de archivos:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryconstellations/
- andromeda.md
- orion.md
Directorystars/
- betelgeuse.md
La siguiente barra lateral se generará automáticamente:
Aprende más sobre las barras laterales generadas automáticamente en la sección grupos autogenerados.
Agregar enlaces y grupos de enlaces
Para configurar los enlaces de tu barra lateral y grupos de enlaces (dentro de un encabezado plegable), usa la propiedad starlight.sidebar
en astro.config.mjs
.
Combinando enlaces y grupos, puedes crear una amplia variedad de diseños de barra lateral.
Enlaces
Agrega un enlace a una página interna o externa usando un objeto con las propiedades label
y link
.
La configuración anterior genera la siguiente barra lateral:
Grupos
Puedes agregar una estructura a tu barra lateral agrupando enlaces relacionados bajo un encabezado plegable. Los Grupos pueden contener tanto enlaces como otros subgrupos.
Agrega un grupo usando un objeto con las propiedades label
y items
.
La label
se utilizará como encabezado del grupo.
Agrega enlaces o subgrupos al arreglo items
.
La configuración anterior genera la siguiente barra lateral:
Grupos autogenerados
Starlight puede generar automáticamente un grupo en tu barra lateral basado en un directorio de tu documentación. Esto es útil cuando no deseas ingresar manualmente cada elemento de la barra lateral en un grupo.
Por defecto, las páginas se ordenan en orden alfabético según el slug
del archivo.
Agrega un grupo autogenerado usando un objeto con las propiedades label
y autogenerate
. Tu configuración autogenerate
debe especificar el directory
para usar en las entradas de la barra lateral. Por ejemplo, con la siguiente configuración:
Y la siguiente estructura de archivos:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryconstellations/
- carina.md
- centaurus.md
Directoryseasonal/
- andromeda.md
La siguiente barra lateral se generará automáticamente:
Personalización de enlaces autogenerados en el frontmatter
Usa el campo sidebar
en las páginas individuales para personalizar los enlaces autogenerados.
Las opciones del frontmatter de la barra lateral te permiten establecer un etiqueta personalizada o agregar una insignia a un enlace, ocultar un enlace de la barra lateral o definir un peso de ordenación personalizado.
Un grupo autogenerado que incluye una página con el frontmatter anterior generará la siguiente barra lateral:
Insignias
Los enlaces, grupos y grupos autogenerados también pueden incluir una propiedad badge
para mostrar una insignia junto a la etiqueta del enlace.
La configuración anterior genera la siguiente barra lateral:
Variantes de insignia
Personaliza el estilo de la insignia usando un objeto con las propiedades text
y variant
.
La propiedad text
representa el contenido a mostrar (por ejemplo, “Nuevo”).
Remplaza el estilo default
, que usa el color de acento de tu sitio, estableciendo la propiedad variant
a uno de los siguientes valores: note
, tip
, danger
, caution
o success
.
La configuración anterior genera la siguiente barra lateral:
Atributos HTML personalizados
Los enlaces también pueden incluir una propiedad attrs
para agregar atributos HTML personalizados al elemento de enlace.
En el siguiente ejemplo, attrs
se usa para agregar un atributo target="_blank"
, de modo que el enlace se abra en una nueva pestaña, y para aplicar un atributo style
personalizado para poner en cursiva la etiqueta del enlace:
La configuración anterior genera la siguiente barra lateral:
Internacionalización
Usa la propiedad translations
en las entradas de enlace y grupo para traducir la etiqueta del enlace o grupo para cada idioma compatible especificando una etiqueta de idioma BCP-47, p. ej. "en"
, "ar"
, o "zh-CN"
, como clave, y la etiqueta traducida como valor.
La propiedad label
se utilizará para el idioma predeterminado y para los idiomas sin traducción.
Navegar por la documentación en portugués de Brasil generará la siguiente barra lateral:
Grupos colapsables
Los grupos de enlaces pueden colapsarse por defecto estableciendo la propiedad collapsed
en true
.
La configuración anterior genera la siguiente barra lateral:
Grupos autogenerados respetan el valor collapsed
de su grupo padre:
La configuración anterior genera la siguiente barra lateral:
Este comportamiento puede remplazarse definiendo la propiedad autogenerate.collapsed
.
La configuración anterior genera la siguiente barra lateral: