Обновление Starlight за апрель

🌸 Вокруг цветут цветы — и Starlight тоже растёт. Посмотрим, что нового!

Мы идём по roadmap к релизу v1 позже в этом году. Вот главное из последних релизов:

Встроенные якорные ссылки заголовков
Поддержка Tailwind v4
CSS cascade layers
Улучшенные API для <head>

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

npx @astrojs/upgrade

Heading anchor links

Starlight v0.34 добавляет встроенную поддержку кликабельных якорных ссылок рядом с заголовками в Markdown, MDX и Markdoc.

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

Мы опирались на исследование доступности Amber Wilson, чтобы сделать якорные ссылки полезными для всех пользователей.

Starlight размещает элемент ссылки под заголовком в HTML и автоматически генерирует доступную метку из Markdown. Например, такой Markdown:

## Get started

сгенерирует HTML примерно такой:

<h2 id="get-started">Get started</h2>
<a href="#get-started">Section titled “Get started”</a>

Это сохраняет структуру документа без лишних якорей в заголовках, а ссылки остаются с понятной меткой для вспомогательных технологий. Мы давно используем этот подход в документации Astro и рады сделать его доступным всем сайтам на Starlight!

Tailwind v4 support

Starlight поддерживает стили на Tailwind CSS почти с первого релиза через кастомный плагин Tailwind. Теперь мы обновили поддержку для совместимости с Tailwind v4!

Tailwind v4 приносит большие изменения. Поддержка теперь через Vite-плагин, а конфигурация переехала в CSS-файл вместо JS-модуля. Стили совместимости Starlight с Tailwind нужно импортировать напрямую в CSS и настраивать через директиву @theme:

/* Include the "starlight" layer alongside Tailwind’s default layers. */
@layer base, starlight, theme, components, utilities;

/* Import Starlight’s compatibility styles. */
@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  /* Configure Starlight theme variables. */
}

Подробности обновления — в changelog @astrojs/starlight-tailwind. Также пригодятся официальное руководство по обновлению Tailwind v4 и руководство Starlight по настройке Tailwind.

CSS cascade layers

Важно, чтобы пользователи Starlight легко настраивали свои сайты. Раньше конфликты между встроенными стилями Starlight и пользовательским CSS мешали кастомизации:

/* Starlight built-in styles (simplified) */
:not(h1, h2, h3, h4, h5, h6) + h2 {
  margin-top: 1.5em;
}

/* User styles */
h2 {
  margin-top: 1em; /* ❌ Doesn’t apply because `h2` is a lower specificity! */
}

Starlight v0.34 решает конфликты, перенося все встроенные стили в отдельный CSS cascade layer starlight. Пользовательские стили всегда имеют приоритет над дефолтными — и можно забыть о битвах специфичности. 👋

/* Starlight built-in styles (simplified) */
@layer starlight.content {
  :not(h1, h2, h3, h4, h5, h6) + h2 {
    margin-top: 1.5em;
  }
}

/* User styles */
h2 {
  margin-top: 1em; /* ✅ Applies because it’s in the top layer! */
}

Это также значит, что можно использовать @layer для организации своего CSS без постоянного перекрытия стилями Starlight.

Подробнее о cascade layers — в руководстве Starlight «CSS & Styling».

Improved <head> APIs

В Starlight v0.33 мы добавили свойство head в объект route data. Это даёт полный контроль над тегами <head> Starlight в route middleware, в том числе для плагинов — проще добавлять теги и фильтровать дефолтные.

Например, этот middleware использует демо Open Graph image API Railway, чтобы добавить мета-теги og:image на каждую страницу Starlight:

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

export const onRequest = defineRouteMiddleware((context) => {
  const { entry, head } = context.locals.starlightRoute;

  // Create an Open Graph image URL using the current page’s title.
  const ogImageUrl = new URL(
    'https://og.railway.com/api/image?fileType=png&layoutName=simple',
  );
  ogImageUrl.searchParams.set('text', entry.data.title);

  // Add a `<meta property="og:image">` tag to the current page’s `<head>`.
  head.push({
    tag: 'meta',
    attrs: { property: 'og:image', content: ogImageUrl.href },
  });
});

Bug fixes and more

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

Thanks

Спасибо всем, кто внёс вклад в недавние релизы PR и ревью: HiDeoo, Dhruv Bhanushali, Hippo, mayank99, Mark Gaze, Matthew Justice, Ariel K, techfg, jsparkdev, trueberryless, Juan Diaz, dragomano, Armand Philippot, Ayo Ayco, Oluwatobi Sofela, liruifengv, Lars Kappert, Emilien Guilmineau, Florian Lefebvre, Emanuele Stoppa, Ervins Strauhmanis, Pejyuu и Sarah Rainsberger.

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