Starlight 0.32

Вышел Starlight 0.32! Разберём новинки на пути к релизу v1.

🧘 Мы работаем над расширяемостью Starlight. Вот последние шаги к большей гибкости:

• Route data middleware
• Новые i18n API для плагинов
• Обновлённые хуки плагинов
• Мультисайтовый поиск

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

npx @astrojs/upgrade

A new route data paradigm

Система переопределения компонентов Starlight позволяет настраивать внешний вид сайта своими компонентами. Это отлично для расширения UI, но со временем мы заметили: люди также используют overrides для изменения данных компонентов, сохраняя встроенные компоненты Starlight.

Чтобы упростить этот сценарий, v0.32 вводит новую систему route middleware с полным доступом к модели данных Starlight без переопределения компонентов. Особенно полезно для плагинов — меньше конфликтов, когда несколько плагинов переопределяют один компонент.

Как middleware Astro, route middleware вызывается при каждом рендере страницы Starlight и позволяет изменить данные до рендеринга. Мощный способ реализовать логику, недоступную только через конфигурацию.

В примере ниже мы делаем документацию веселее, добавляя восклицательные знаки к заголовку каждой страницы!!!

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 + '!!!';
});

Подробности — в руководстве «Route Data».

Breaking changes

Для лучшей поддержки route middleware мы изменили способ получения route data встроенными компонентами Starlight.

Раньше все шаблонные компоненты Starlight, включая пользовательские и плагиновые overrides, получали объект данных текущего маршрута через Astro.props. Теперь эти данные доступны как Astro.locals.starlightRoute.

Подробности миграции — в changelog Starlight.

New i18n APIs for plugins

Этот релиз даёт плагинам полный доступ к встроенной системе интернационализации Starlight.

Плагины теперь могут вызывать useTranslations() в хуке config:setup для доступа к любым UI-строкам Starlight. Это открывает локализованное логирование, переводы в Markdown-плагинах и многое другое.

Этот плагин логирует строку Starlight «Built with Starlight» и использует перевод для локали пользователя, если он доступен:

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

Updated plugin hooks

В рамках доработки переводов в плагинах мы разделили старый хук setup на два: i18n:setup и config:setup. Хук setup устарел — плагины должны мигрировать на config:setup:

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

Плагинам с утилитой injectTranslations() нужно перенести её в отдельный хук 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' },
        });
      },
    },
  };

Multisite search support

Starlight предоставляет поиск по сайту из коробки через Pagefind. Этот релиз открывает конфигурацию мультисайтового поиска Pagefind — можно искать по нескольким сайтам.

Например, если основной сайт на example.com проиндексирован Pagefind, а Starlight развёрнут на поддомене docs.example.com, результаты поиска с основного сайта можно показать в документации через опцию 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' }],
      },
    }),
  ],
});

Подробности конфигурации — в руководстве Pagefind «Searching multiple sites».

Bug fixes and more

Как всегда, с релиза v0.31 мы исправляли ошибки. Подробности и руководство по миграции — в changelog Starlight.

Thanks

Спасибо всем, кто внёс вклад в этот релиз PR и ревью: HiDeoo, Emilien Guilmineau, trueberryless, Sarah Rainsberger, Lorenzo Lewis и Yan Thomas.

Ждём, что вы построите со Starlight 0.32! Вопросы, комментарии или просто «привет» — в Astro Discord.