Starlight 0.35

🌟 Starlight 0.35 — летний релиз, который делает кастомизацию документации проще, чем когда-либо.

Разберём главное в этом релизе:

Кастомные иконки в asides
Кастомные атрибуты для автогенерируемых ссылок sidebar
Кастомная обработка slug страниц

Чтобы обновить существующий сайт на Starlight, используйте автоматизированный CLI @astrojs/upgrade. Он обновит Starlight, Astro и другие интеграции:

npx @astrojs/upgrade

Custom icons in asides

Asides Starlight упрощают добавление стилизованных заметок, предупреждений и других callout на страницы документации. Starlight 0.35 идёт дальше — теперь можно переопределить иконку aside.

Добавьте атрибут icon к aside для кастомизации иконки — в Markdown, MDX и 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 %}

Сейчас asides можно стилизовать встроенными иконками Starlight, но мы планируем расширить это поддержкой кастомных иконок в будущем.

Спасибо Shubham Padia за эту функцию!

Starlight 0.35 добавляет поддержку применения кастомных HTML-атрибутов ко всем ссылкам в автогенерируемой группе sidebar. Это упрощает добавление стиля или поведения ко всем ссылкам в части sidebar.

Используйте новую опцию autogenerate.attrs в конфигурации sidebar. Например, можно курсивом выделить все ссылки в конкретной автогенерируемой группе:

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' },
      },
    },
  ],
}),

Custom page slug processing

Теперь проще настраивать, как имена файлов документации сопоставляются с URL.

По умолчанию Astro использует популярный пакет github-slugger для нормализации имён файлов контента. Например, содержимое Example.File.md доступно по /examplefile. Это обеспечивает согласованный вывод и совместимость URL со многими платформами.

Если нужна другая нормализация, передайте опцию generateId в docsLoader() Starlight в конфигурации контента. Следующий пример не нормализует имена, а только убирает расширения файлов:

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(),
  }),
};

Bug fixes and more

Как всегда, мы исправляли ошибки и расширяли существующие функции. Changelog Starlight содержит все подробности, включая руководство по миграции для breaking changes.

Вот несколько более заметных изменений в 0.35:

Markdown plugins now limited to docs content

Markdown-контент вне коллекции src/content/docs/ Starlight больше не обрабатывается дефолтными remark и rehype плагинами Starlight. Это улучшает совместимость с сайтами, использующими Markdown на не-Starlight страницах.

Если вы полагались на прежнее поведение — напишите нам! Откройте GitHub Discussion и расскажите о вашем сценарии.

Banner content is now excluded from search results

Контент, добавленный через свойство frontmatter banner Starlight, больше не индексируется дефолтным поисковым провайдером Pagefind. Это исправляет неожиданное поведение в модальном окне поиска.