Starlight 0.32 | Astro en Español

¡Starlight 0.32 ya está aquí! Vamos a desempaquetar las novedades mientras avanzamos hacia un lanzamiento v1.

🧘 Nos hemos estado estirando para hacer Starlight extra extensible. Aquí está nuestro último flujo para más flexibilidad:

Middleware de datos de ruta
Nuevas APIs de i18n para plugins
Hooks de plugin actualizados
Soporte de búsqueda multisitio

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

Un nuevo paradigma de datos de ruta

El sistema de sobrescritura de componentes de Starlight permite a los usuarios personalizar la apariencia de un sitio con sus propios componentes. Esto es genial para extender la UI de Starlight, pero con el tiempo, vimos un patrón donde la gente también usaba sobrescrituras para modificar los datos de los componentes, mientras seguían reutilizando los componentes integrados de Starlight.

Para facilitar este caso de uso, v0.32 introduce un nuevo sistema de middleware de ruta que proporciona acceso completo al modelo de datos de Starlight sin necesidad de sobrescribir ningún componente. Esto es particularmente útil para plugins, ya que evita conflictos comunes donde varios plugins intentaban sobrescribir el mismo componente.

Similar al sistema de middleware de Astro, el middleware de ruta se llama para cada renderizado de página de Starlight y te da la oportunidad de modificar cualquier dato antes de que se renderice. Esta es una forma potente de implementar lógica personalizada que actualmente no es posible con la configuración por sí sola.

En el siguiente ejemplo, intentamos hacer nuestra documentación más emocionante añadiendo signos de exclamación al final del título de cada página!!!

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

export const onRequest = defineRouteMiddleware((context) => {
  // Get the content collection entry for this page.
  const { entry } = context.locals.starlightRoute;
  // Update the title to add exclamation marks.
  entry.data.title = entry.data.title + '!!!';
});

Consulta la guía de "Datos de Ruta" para obtener todos los detalles sobre cómo escribir middleware de ruta.

Cambios disruptivos

Para soportar mejor el middleware de ruta, hemos actualizado cómo los componentes por defecto de Starlight reciben los datos de ruta.

Anteriormente, todos los componentes de plantillas de Starlight, incluyendo las sobrescrituras de usuarios o plugins, tenían acceso a un objeto de datos para la ruta actual vía Astro.props. Estos datos ahora están disponibles como Astro.locals.starlightRoute en su lugar.

Consulta el changelog de Starlight para todos los detalles sobre cómo migrar a este nuevo enfoque.

Nuevas APIs de i18n para plugins

Este lanzamiento da a los plugins acceso completo al potente sistema de internacionalización integrado de Starlight.

Los plugins ahora pueden llamar a useTranslations() en el hook config:setup para acceder a cualquiera de las cadenas de UI de Starlight. Esto abre posibilidades para logs localizados, usar traducciones en plugins de Markdown y más.

Este plugin de ejemplo registra la cadena de texto por defecto de Starlight “Built with Starlight” y usa la traducción que coincide con el idioma del usuario si está disponible:

export default {
  name: 'localizedPlugin',
  hooks: {
    'config:setup'({ useTranslations, logger }) {
      // Detect the current user’s preferred locale.
      const userLocale = Intl.DateTimeFormat().resolvedOptions().locale;
      // Get a `t()` function for the locale.
      const t = useTranslations(userLocale);
      // Log the localized string.
      logger.info(t('builtWithStarlight.label'));
    },
  },
};

Hooks de plugin actualizados

Como parte del rediseño para soportar el uso de traducciones en plugins, hemos dividido el antiguo hook setup en dos: i18n:setup y config:setup. El uso del hook setup está deprecado y los plugins deberían migrar a usar config:setup en su lugar:

  export default {
    name: 'starlight-plugin',
    hooks: {
      'setup'({ config }) {
      'config:setup'({ config }) {
        // Your plugin configuration setup code
      },
    },
  };

Los plugins que usan la utilidad injectTranslations() necesitan moverla al hook dedicado i18n:setup:

  export default {
    name: 'plugin-with-translations',
    hooks: {
      'config:setup'({ injectTranslations }) {
      'i18n:setup'({ injectTranslations }) {
        injectTranslations({
          en: { 'myPlugin.doThing': 'Do the thing' },
          fr: { 'myPlugin.doThing': 'Faire le truc' },
        });
      },
    },
  };

Soporte de búsqueda multisitio

Starlight proporciona búsqueda en el sitio lista para usar con Pagefind. Este lanzamiento expone la configuración de búsqueda multisitio de Pagefind, para que puedas soportar la búsqueda a través de múltiples sitios.

Por ejemplo, si tienes un sitio principal en example.com indexado con Pagefind y tu sitio de Starlight desplegado en el subdominio docs.example.com, puedes mostrar resultados de búsqueda de tu sitio principal en tu documentación con la opción de configuración mergeIndex:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://docs.example.com/',
  integrations: [
    starlight({
      title: 'Docs with multisite search',
      pagefind: {
        mergeIndex: [{ bundlePath: 'https://example.com/pagefind' }],
      },
    }),
  ],
});

Consulta la guía de Pagefind sobre “Búsqueda en múltiples sitios” para todos los detalles de las opciones de configuración disponibles.

Corrección de errores y más

Como siempre, también hemos estado trabajando para solucionar problemas desde el lanzamiento de v0.31. Consulta el changelog de Starlight para todos los detalles, incluyendo una guía de migración detallada.

Gracias

Gracias a todos los que contribuyeron a este lanzamiento con PRs y revisiones, incluyendo a HiDeoo, Emilien Guilmineau, trueberryless, Sarah Rainsberger, Lorenzo Lewis y Yan Thomas.

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