Starlight 0.28

Автор
Chris Swithinbank
HiDeoo

Вышел Starlight v0.28! В последней версии официального универсального конструктора документации Astro — новые возможности. Разберём главное из недавних релизов Starlight.

Чтобы обновить существующий проект, запустите автоматизированный CLI @astrojs/upgrade в терминале:

npx @astrojs/upgrade

Next-level localization

Starlight был мультиязычным с первого дня, а v0.28 выводит это на новый уровень. Встроенная система локализации Starlight теперь работает на библиотеке i18next и доступна в любом месте сайта.

Используйте новый метод Astro.locals.t() в любом Astro-компоненте, чтобы выводить встроенные UI-метки Starlight или свои строки — с поддержкой интерполяции и плюрализации:

<p>{Astro.locals.t('404.text')}</p>
<!-- <p>Page not found. Check the URL or try using the search bar.</p> -->


<p>{Astro.locals.t('componentCount', { count: 99 })}</p>
<!-- <p>I have 99 components 🎉</p> -->

Это обновление делает Starlight лучшим выбором для интернационализации из коробки. Начните с одного языка сегодня и будьте уверены, что сможете перевести документацию, когда придёт время.

On-demand rendering support

С v0.27 Starlight поддерживает полностью динамический server-side rendering, если он вам нужен. Установите prerender: false в опциях Starlight, чтобы отключить статическую генерацию страниц и перейти в режим on-demand rendering Astro:

astro.config.mjs
starlight({
  title: 'Docs on Demand',
  prerender: false,
}),

Это открывает возможности вроде аутентификации и персонализации, делая Starlight ещё гибче. Посмотрите демо Docs on Demand, чтобы увидеть возможности в действии. Спасибо Fryuni за реализацию этой функции!

Tabs that remember you

Компонент Starlight <Tabs> теперь запоминает предпочтения пользователя при навигации между страницами. Читатель может один раз выбрать менеджер пакетов или ОС — и увидеть этот выбор в других местах документации. Чтобы включить функцию, добавьте совпадающие атрибуты syncKey к <Tabs>:

src/content/docs/example.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';


<Tabs syncKey="package-manager">
  <TabItem label="npm">npm install @astrojs/starlight</TabItem>
  <TabItem label="pnpm">pnpm add @astrojs/starlight</TabItem>
  <TabItem label="yarn">yarn add @astrojs/starlight</TabItem>
</Tabs>

Starlight опирается на проверенные веб-технологии: простой статический HTML и минимум JavaScript для оптимальной производительности. Мы слышали обратную связь: полная перезагрузка страницы сбрасывала состояние sidebar.

С v0.26 Starlight сохраняет и восстанавливает состояние sidebar при навигации благодаря лёгкому custom element — просмотр стал плавнее. Это прогрессивное улучшение: если JavaScript недоступен, sidebar работает как обычно.

Simpler sidebar configuration

В ранних версиях Starlight настройка sidebar могла быть многословной:

astro.config.mjs
starlight({
  title: 'Old Skool Starlight',
  sidebar: [
    { label: 'Page one', link: '/one' },
    { label: 'Page two', link: '/two' },
    // ...
  ],
}),

В Starlight v0.25 для внутренних ссылок это стало проще. Теперь можно указать только slug страницы — Starlight автоматически подставит заголовок как метку ссылки:

astro.config.mjs
starlight({
  title: 'Cutting Edge Starlight',
  sidebar: [
    'one', 'two', // ...
  ],
}),

Бонус: с таким синтаксисом проверка ссылок встроена — меньше случайных 404! Спасибо Lorenzo за эту функцию.

Sparkling fresh docs

Мы также обновили собственную документацию! Переработали документацию по встроенным компонентам Starlight. У каждого компонента теперь отдельная страница с примерами и полным справочником по props.

Посетите новое руководство «Using components», чтобы изучить доступные компоненты.

Конечно, без переводов это были бы не Astro docs. Спасибо @dreyfus92, @jsparkdev, @dragomano, @liruifengv, @zhoushengdao, @Nin3lee, @casungo, @at-the-vr и @thomasbnt за актуальные испанскую, корейскую, русскую, упрощённый китайский, итальянскую, хинди и французскую документацию!

A Markdoc preset for the adventurous

Пользователи Starlight, интересующиеся Markdoc, могут использовать новый пакет @astrojs/starlight-markdoc для быстрой настройки всех встроенных компонентов Starlight в файлах Markdoc. Подробности — в руководстве по настройке Markdoc.

Try Starlight today!

Мы рады видеть, как Cloudflare, Crowdin, StackBlitz, Sentry, Font Awesome и SST выбирают Starlight для документации. Присоединяйтесь к ним и open-source проектам вроде FreeCodeCamp, RealWorld Apps, Biome, Jimp, Shepherd, Bloc и Knip — и начните сегодня.

Посетите документацию Starlight или создайте новый сайт прямо из терминала:

npm create astro@latest -- --template starlight