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

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

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

Ваши CSS стили

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

1. Добавьте CSS-файл в ваш каталог src/. Например, вы можете установить большую ширину колонки по умолчанию и бóльший размер текста для заголовков страниц:

   src/styles/custom.css

   :root {
     --sl-content-width: 50rem;
     --sl-text-5xl: 3.5rem;
   }

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

   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:

src/styles/custom.css

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

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

Tailwind CSS

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

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

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

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

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

npm

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

pnpm

pnpm create astro --template starlight/tailwind

Yarn

yarn create astro --template starlight/tailwind

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

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

1. Настройте Tailwind в вашем проекте, выполнив следующую команду и следуя инструкциям в терминале:

   npm

   npx astro add tailwind

   pnpm

   pnpm astro add tailwind

   Yarn

   yarn astro add tailwind

2. Установите пакет совместимости Tailwind для Starlight:

   npm

   npm install @astrojs/starlight-tailwind

   pnpm

   pnpm add @astrojs/starlight-tailwind

   Yarn

   yarn add @astrojs/starlight-tailwind

3. Замените содержимое файла 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);

4. Обновите конфигурацию Starlight для использования файла CSS Tailwind:

   astro.config.mjs

   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 в своем интерфейсе.

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

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

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);

@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);
}

Темизация

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

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

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

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

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

Заготовки Океан Лес Оксид Туман По умолчанию Случайно

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

AA AAA

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

Выбор цвета

Оттенок 269 Интенсивность 0.27

Серый

Выбор цвета

Оттенок 270 Интенсивность 0.016

Тёмный режим

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

Светлый режим

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

CSS

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

Tailwind

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