CSS и стилизация

Вы можете стилизовать ваш сайт Starlight с помощью CSS-файлов или использовать плагин Starlight Tailwind.

Для быстрого изменения стандартного стиля вашего сайта ознакомьтесь с темами от сообщества.

Ваши CSS стили

Настройте стили, применяемые к вашему сайту Starlight, предоставив дополнительные CSS-файлы для изменения или расширения стандартных стилей Starlight.

Добавьте CSS-файл в ваш каталог src/. Например, вы можете установить большую ширину колонки по умолчанию и бóльший размер текста для заголовков страниц:
src/styles/custom.css
```
:root {
  --sl-content-width: 50rem;
  --sl-text-5xl: 3.5rem;
}
```

Добавьте путь к вашему CSS-файлу в массив customCss Starlight в astro.config.mjs:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Документация с изменёнными CSS-стилями',
      customCss: [
        // Относительный путь к вашему CSS файлу
        './src/styles/custom.css',
      ],
    }),
  ],
});

Вы можете увидеть все кастомные свойства CSS, используемые Starlight, которые вы можете установить для настройки вашего сайта, в файле props.css на GitHub.

Каскадные слои

Starlight использует каскадные слои внутри для управления порядком своих стилей. Это обеспечивает предсказуемый порядок CSS и упрощает переопределение стилей. Любые пользовательские CSS-стили без слоёв переопределят стандартные стили Starlight.

Если вы используете каскадные слои, вы можете применить @layer в вашем пользовательском CSS для определения порядка приоритета различных слоёв относительно стилей из слоя starlight:

@layer my-reset, starlight, my-overrides;

Пример выше определяет пользовательский слой my-reset, применяемый перед всеми слоями Starlight, и другой слой my-overrides, применяемый после всех слоёв Starlight. Любые стили в слое my-overrides будут иметь приоритет над стилями Starlight, но Starlight всё ещё сможет изменять стили, установленные в слое my-reset.

Tailwind CSS

Поддержка Tailwind CSS v4 в проектах Astro обеспечивается плагином Tailwind Vite. Starlight предоставляет дополнительный CSS для настройки Tailwind, обеспечивающий совместимость со стилями Starlight.

CSS Tailwind от Starlight применяет следующую конфигурацию:

Настраивает dark: варианты Tailwind для работы с тёмным режимом Starlight.
Использует цвета и шрифты темы Tailwind в пользовательском интерфейсе Starlight.
Восстанавливает основные части стилей сброса Preflight от Tailwind.

Создание нового проекта с Tailwind

Создайте новый проект Starlight с предварительно настроенным Tailwind CSS, используя create astro:

npm create astro@latest -- --template starlight/tailwind

pnpm create astro --template starlight/tailwind

yarn create astro --template starlight/tailwind

Добавление Tailwind в существующий проект

Если у вас уже есть сайт на Starlight и вы хотите добавить Tailwind CSS, следуйте этим шагам.

Настройте Tailwind в вашем проекте, выполнив следующую команду и следуя инструкциям в терминале:
- npm
- pnpm
- Yarn
Окно терминала
npx astro add tailwind
Окно терминала
pnpm astro add tailwind
Окно терминала
yarn astro add tailwind
Установите пакет совместимости Tailwind для Starlight:
- npm
- pnpm
- Yarn
Окно терминала
npm install @astrojs/starlight-tailwind
Окно терминала
pnpm add @astrojs/starlight-tailwind
Окно терминала
yarn add @astrojs/starlight-tailwind
Замените содержимое файла src/styles/global.css, созданного Astro, для обеспечения совместимости со Starlight:
src/styles/global.css
```
@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
```
Эта конфигурация темы Tailwind определяет порядок каскадных слоев Starlight, импортирует дополнительные стили Tailwind от Starlight, а также стили темы и утилиты Tailwind. Если вашему проекту требуется дополнительная конфигурация Tailwind, ознакомьтесь с разделом Использование нескольких конфигураций Tailwind.

Обновите конфигурацию Starlight, добавив файл Tailwind CSS как первый элемент массива customCss:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs with Tailwind',
      customCss: [
        // Путь к базовым стилям Tailwind:
        './src/styles/global.css',
      ],
    }),
  ],
  vite: { plugins: [tailwindcss()] },
});

Стилизация Starlight с использованием Tailwind

При создании нового проекта Starlight с Tailwind или при добавлении Tailwind в существующий проект Starlight, Starlight будет использовать значения из вашей конфигурации темы Tailwind, расположенной в файле src/styles/global.css, для стилизации своего пользовательского интерфейса.

Если установлены, следующие пользовательские свойства CSS переопределят стили Starlight по умолчанию:

--color-accent-* — используется для ссылок и выделения текущего элемента;
--color-gray-* — используется для цветов фона и границ;
--font-sans — используется для текста в интерфейсе и контента;
--font-mono — используется для примеров кода.

@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  /* Предпочитаемый шрифт для текста. По умолчанию Starlight использует системный стек шрифтов. */
  --font-sans: 'Atkinson Hyperlegible';
  /* Предпочитаемый шрифт для кода. По умолчанию Starlight использует системные моноширинные шрифты. */
  --font-mono: 'IBM Plex Mono';
  /* Предпочитаемый акцентный цвет. Indigo наиболее близок к цветам по умолчанию в Starlight. */
  --color-accent-50: var(--color-indigo-50);
  --color-accent-100: var(--color-indigo-100);
  --color-accent-200: var(--color-indigo-200);
  --color-accent-300: var(--color-indigo-300);
  --color-accent-400: var(--color-indigo-400);
  --color-accent-500: var(--color-indigo-500);
  --color-accent-600: var(--color-indigo-600);
  --color-accent-700: var(--color-indigo-700);
  --color-accent-800: var(--color-indigo-800);
  --color-accent-900: var(--color-indigo-900);
  --color-accent-950: var(--color-indigo-950);
  /* Предпочитаемая серая палитра. Zinc наиболее близок к значениям по умолчанию в Starlight. */
  --color-gray-50: var(--color-zinc-50);
  --color-gray-100: var(--color-zinc-100);
  --color-gray-200: var(--color-zinc-200);
  --color-gray-300: var(--color-zinc-300);
  --color-gray-400: var(--color-zinc-400);
  --color-gray-500: var(--color-zinc-500);
  --color-gray-600: var(--color-zinc-600);
  --color-gray-700: var(--color-zinc-700);
  --color-gray-800: var(--color-zinc-800);
  --color-gray-900: var(--color-zinc-900);
  --color-gray-950: var(--color-zinc-950);
}

Использование нескольких конфигураций Tailwind

Несколько конфигураций Tailwind могут быть использованы для применения различных стилей к разным частям вашего сайта, например, при использовании Starlight с подкаталогами или при добавлении пользовательских страниц на ваш сайт. Например, вы можете захотеть использовать стили сброса Preflight от Tailwind на пользовательских страницах, сохраняя при этом слой совместимости Starlight для страниц Starlight.

Следующая конфигурация Tailwind CSS настраивает Tailwind без каких-либо плагинов или дополнительной конфигурации и может использоваться как отправная точка для страниц, не относящихся к Starlight:

/* Загрузка Tailwind без дополнительных стилей от Starlight. */
@import 'tailwindcss';

Для страниц Starlight примените предпочитаемую конфигурацию Tailwind CSS, следуя инструкциям из раздела Добавление Tailwind в существующий проект.
Для других страниц примените предпочитаемую конфигурацию Tailwind CSS, импортируя её на этих страницах. Это часто делается в компоненте макета, чтобы стили Tailwind могли использоваться на всех страницах, использующих этот макет.
src/layouts/CustomPageLayout.astro
```
---
import '../styles/custom-pages-tailwind.css';
---
```

Чтобы узнать больше о конфигурациях тем Tailwind, ознакомьтесь с документацией Tailwind CSS.

Темизация

Цветовая тема Starlight может быть настроена путем переопределения её стандартных кастомных свойств. Эти переменные используются по всему интерфейсу, причём различные оттенки серого используются для текста и цветов фона, а акцентный цвет используется для ссылок и выделения текущих элементов в навигации.

Редактор цветовой темы

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

Используйте параметр «Уровень контрастности», чтобы указать, какому из стандартов цветовой контрастности должен соответствовать веб-контент.

Когда вы будете довольны внесёнными изменениями, скопируйте приведённый ниже код CSS или Tailwind и используйте его в своем проекте.

Заготовки

Уровень контрастности

AA AAA

Акцентный цвет

Оттенок 269

Интенсивность 0.27

Серый

Оттенок 270

Интенсивность 0.016

Тёмный режим

Основной текст отображается в оттенке серого с высоким контрастом по отношению к фону. Ссылки выделены цветом. Некоторый текст, например, оглавление, имеет меньший контраст. Встроенный код имеет выделенный фон.

Добавьте следующий CSS в ваш проект в пользовательском CSS-файле, чтобы применить эту тему к вашему сайту.

Добавьте следующие CSS-переменные в блок @theme вашего файла Tailwind CSS, чтобы применить эту тему к вашему сайту.