Starlight 0.35 | Astro en Español

🌟 Starlight 0.35 quiere ser tu icono del verano con un lanzamiento que hace que personalizar tu documentación sea más fácil que nunca.

Echemos un vistazo a los destacados de este lanzamiento:

Iconos personalizados en apartados
Atributos personalizados para enlaces autogenerados de la barra lateral
Procesamiento personalizado de slugs de página

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

Iconos personalizados en apartados

Los apartados de Starlight facilitan añadir notas con estilo, advertencias y otros tipos de llamadas de atención a tus páginas de documentación. Starlight 0.35 lleva esto un paso más allá, permitiéndote sobrescribir el icono de un apartado.

Añade un atributo icon a tu apartado para personalizar el icono, con soporte en páginas Markdown, MDX y Markdoc:

:::tip{icon="heart"}
Show your love with a heart icon.
:::

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" icon="heart">
  Show your love with a heart icon.
</Aside>

{% aside type="tip" icon="heart" %}
Show your love with a heart icon.
{% /aside %}

Actualmente, los apartados pueden estilizarse usando los iconos integrados de Starlight, pero estamos planeando expandir esto para incluir soporte de iconos personalizados en un futuro lanzamiento.

¡Gracias a Shubham Padia por contribuir esta función!

Starlight 0.35 añade soporte para aplicar atributos HTML personalizados a todos los enlaces en un grupo autogenerado de la barra lateral. Esto facilita añadir un estilo o comportamiento personalizado a todos los enlaces de parte de tu barra lateral.

Usa la nueva opción autogenerate.attrs en tu configuración de barra lateral para añadir atributos personalizados. Por ejemplo, podrías decidir poner en cursiva todos los enlaces en un grupo autogenerado específico:

starlight({
  title: 'My docs',
  sidebar: [
    {
      label: 'Constellations',
      autogenerate: {
        // Autogenerate a group of links for the 'constellations' directory.
        directory: 'constellations',
        // Italicize all link labels in this group.
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
}),

Procesamiento personalizado de slugs de página

Ahora es más fácil personalizar cómo los nombres de tus archivos de documentación se mapean a URLs.

Por defecto, Astro usa el paquete popular github-slugger para normalizar los nombres de archivos de contenido. Por ejemplo, el contenido en Example.File.md se sirve en /examplefile. Esto asegura una salida consistente y compatibilidad de URL con muchas plataformas comunes.

Sin embargo, si necesitas personalizar esta normalización, ahora puedes pasar una opción generateId al docsLoader() de Starlight en tu configuración de contenido. El siguiente ejemplo evita toda normalización y simplemente elimina las extensiones de archivo de los archivos de contenido:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: docsLoader({
      // Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
      generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
    }),
    schema: docsSchema(),
  }),
};

Corrección de errores y más

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

Aquí hay algunos de los cambios más grandes en 0.35:

Plugins de Markdown ahora limitados al contenido de docs

El contenido Markdown fuera de la colección src/content/docs/ de Starlight ya no es procesado por los plugins remark y rehype por defecto de Starlight. Esto mejora la compatibilidad con sitios que usan contenido Markdown en páginas que no son de Starlight.

Si dependías del comportamiento anterior, ¡nos encantaría saber de ti! Por favor abre una Discusión de GitHub para contarnos tu caso de uso.

El contenido del banner ahora se excluye de los resultados de búsqueda

El contenido añadido usando la propiedad frontmatter banner de Starlight ya no es indexado por nuestro proveedor de búsqueda por defecto Pagefind. Esto soluciona algunos comportamientos inesperados en el modal de búsqueda.