Actualización de Abril de Starlight

Por
Chris Swithinbank

🌸 Flores por todas partes y Starlight también está creciendo. ¡Echemos un vistazo y veamos qué hay de nuevo!

Hemos estado trabajando en nuestra hoja de ruta hacia el lanzamiento de v1 más adelante este año. Aquí hay algunos destacados de nuestros últimos lanzamientos:

Para actualizar un sitio existente de Starlight, usa la herramienta CLI automatizada @astrojs/upgrade. Esto actualizará Starlight, Astro y cualquier otra integración que estés usando:

npx @astrojs/upgrade

Starlight v0.34 añade soporte integrado para renderizar automáticamente enlaces de anclaje clicables junto a los encabezados en tu contenido Markdown, MDX y Markdoc.

Un subencabezado en la documentación de Starlight que muestra un cursor de puntero sobre un icono de enlace de anclaje.

Construimos sobre la investigación de accesibilidad de Amber Wilson para diseñar un enfoque de enlaces de anclaje que busca ser útil para todos los usuarios.

Starlight coloca el elemento del enlace debajo del encabezado en la salida HTML y genera automáticamente una etiqueta accesible a partir de tu contenido Markdown. Por ejemplo, el siguiente Markdown:

## Get started

generará HTML más o menos así:

<h2 id="get-started">Get started</h2>
<a href="#get-started">Section titled “Get started”</a>

Esto asegura que los encabezados en la estructura del documento no estén saturados por enlaces de anclaje y que los enlaces mismos sigan teniendo una etiqueta clara disponible para tecnología asistiva. ¡Hemos estado usando este enfoque en la documentación de Astro desde hace un tiempo y estamos emocionados de hacerlo disponible para todos los sitios construidos con Starlight!

Soporte para Tailwind v4

Starlight ha soportado la creación de estilos con Tailwind CSS desde poco después de nuestro primer lanzamiento mediante un plugin personalizado de Tailwind. ¡Ahora hemos actualizado nuestro soporte para compatibilidad con Tailwind v4!

Tailwind v4 viene con algunos cambios importantes. El soporte ahora se proporciona mediante un plugin de Vite y la configuración se ha movido a un archivo CSS en lugar de un módulo JS. Los estilos de compatibilidad de Tailwind de Starlight ahora deben importarse directamente en tu CSS y personalizarse usando la directiva @theme:

src/styles/global.css
/* Include the "starlight" layer alongside Tailwind’s default layers. */
@layer base, starlight, theme, components, utilities;


/* Import Starlight’s compatibility styles. */
@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);


@theme {
  /* Configure Starlight theme variables. */
}

Para una guía detallada sobre la actualización, consulta el changelog de @astrojs/starlight-tailwind. También puede que quieras tener a mano la guía oficial de actualización de Tailwind v4 y la guía de configuración de Tailwind de Starlight.

Capas de cascada CSS

Es importante que los usuarios de Starlight puedan personalizar fácilmente sus sitios. Históricamente, los conflictos entre los estilos integrados de Starlight y el CSS del usuario hacían que la experiencia de personalización fuera menos fluida de lo que podría haber sido:

/* Starlight built-in styles (simplified) */
:not(h1, h2, h3, h4, h5, h6) + h2 {
  margin-top: 1.5em;
}


/* User styles */
h2 {
  margin-top: 1em; /* ❌ Doesn’t apply because `h2` is a lower specificity! */
}

Starlight v0.34 resuelve conflictos moviendo todos los estilos integrados a una capa de cascada CSS starlight dedicada. Esto significa que los estilos del usuario siempre tendrán precedencia sobre los estilos por defecto y podemos despedirnos de las batallas de especificidad. 👋

/* Starlight built-in styles (simplified) */
@layer starlight.content {
  :not(h1, h2, h3, h4, h5, h6) + h2 {
    margin-top: 1.5em;
  }
}


/* User styles */
h2 {
  margin-top: 1em; /* ✅ Applies because it’s in the top layer! */
}

Este cambio también significa que puedes disfrutar los beneficios de usar @layer para organizar tu propio CSS sin que los estilos de Starlight siempre lo sobrescriban.

Aprende más sobre el uso de capas de cascada en la guía de “CSS y Estilos” de Starlight.

APIs de <head> mejoradas

En Starlight v0.33, añadimos una nueva propiedad head a nuestro objeto de datos de ruta. Esto desbloquea control total sobre las etiquetas <head> de Starlight en el middleware de ruta, incluyendo para plugins, permitiéndote añadir etiquetas y filtrar las etiquetas por defecto más fácilmente.

Por ejemplo, este middleware usa el API de imágenes Open Graph de demo de Railway para añadir meta etiquetas og:image a cada página de Starlight:

src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';


export const onRequest = defineRouteMiddleware((context) => {
  const { entry, head } = context.locals.starlightRoute;


  // Create an Open Graph image URL using the current page’s title.
  const ogImageUrl = new URL(
    'https://og.railway.com/api/image?fileType=png&layoutName=simple',
  );
  ogImageUrl.searchParams.set('text', entry.data.title);


  // Add a `<meta property="og:image">` tag to the current page’s `<head>`.
  head.push({
    tag: 'meta',
    attrs: { property: 'og:image', content: ogImageUrl.href },
  });
});

Corrección de errores y más

Como siempre, también hemos estado trabajando para solucionar problemas y extender funciones existentes. Consulta el changelog de Starlight para todos los detalles, incluyendo la guía de migración para cambios disruptivos.

Gracias

Gracias a todos los que contribuyeron a nuestros lanzamientos recientes con PRs y revisiones, incluyendo a HiDeoo, Dhruv Bhanushali, Hippo, mayank99, Mark Gaze, Matthew Justice, Ariel K, techfg, jsparkdev, trueberryless, Juan Diaz, dragomano, Armand Philippot, Ayo Ayco, Oluwatobi Sofela, liruifengv, Lars Kappert, Emilien Guilmineau, Florian Lefebvre, Emanuele Stoppa, Ervins Strauhmanis, Pejyuu y Sarah Rainsberger.

¡Esperamos ver qué construyes con Starlight! Si tienes preguntas, comentarios o solo quieres saludar, pásate por el Discord de Astro.