CSS & 스타일링

사용자 정의 CSS 파일을 사용하여 Starlight 사이트의 스타일을 지정하거나 Starlight Tailwind 플러그인을 사용할 수 있습니다.

사이트의 기본 스타일을 빠르게 변경하려면 커뮤니티 테마를 확인하세요.

사용자 정의 CSS 스타일

Starlight의 기본 스타일을 수정하거나 확장하기 위한 CSS 파일을 제공하여 사이트에 적용된 스타일을 원하는대로 변경할 수 있습니다.

src/ 디렉터리에 CSS 파일을 추가합니다. 예를 들어, 아래 코드를 통해 페이지 제목을 더 넓게 만들고, 더 큰 텍스트를 사용할 수 있습니다.
src/styles/custom.css
```
:root {
  --sl-content-width: 50rem;
  --sl-text-5xl: 3.5rem;
}
```

astro.config.mjs 파일에 있는 Starlight의 customCss 배열에 CSS 파일 경로를 추가하세요.

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

export default defineConfig({
  integrations: [
    starlight({
      title: '사용자 정의 CSS를 사용한 문서',
      customCss: [
        // 사용자 정의 CSS 파일의 상대 경로
        './src/styles/custom.css',
      ],
    }),
  ],
});

사이트를 스타일링하기 위해 Starlight에서 사용되는 모든 CSS 속성을 props.css 파일에서 확인할 수 있습니다.

캐스케이드 레이어

Starlight는 스타일 순서를 관리하기 위해 내부적으로 캐스케이드 레이어를 사용합니다. 이를 통해 예측 가능한 CSS 순서를 보장하고 더 간단한 재정의를 할 수 있습니다. 레이어가 지정되지 않은 사용자 정의 CSS는 starlight 레이어의 기본 스타일을 재정의합니다.

캐스케이드 레이어를 사용하고 있다면, 사용자 정의 CSS에서 @layer를 사용하여 Starlight 스타일을 기준으로 서로 다른 레이어의 우선순위를 정의할 수 있습니다.

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

위 예시는 my-reset이라는 사용자 정의 레이어를 정의하며, 이는 모든 Starlight 레이어보다 먼저 적용됩니다. 또 다른 레이어인 my-overrides는 모든 Starlight 레이어 이후에 적용됩니다. my-overrides 레이어의 모든 스타일은 Starlight의 스타일보다 우선 적용되지만, Starlight는 여전히 my-reset 레이어에 설정된 스타일을 변경할 수 있습니다.

Tailwind CSS

Astro 프로젝트의 Tailwind CSS 지원은 Tailwind Vite 플러그인을 통해 제공됩니다. Starlight는 Starlight 스타일과 호환되도록 Tailwind를 구성하는 데 도움이 되는 보완 CSS를 제공합니다.

Starlight Tailwind CSS는 다음 구성을 적용합니다.

Starlight의 다크 모드와 작동하도록 Tailwind의 dark: 변형을 구성합니다.
Starlight UI에서 Tailwind 테마 색상 및 글꼴을 사용합니다.
Tailwind Preflight 리셋 스타일의 필수적인 부분을 복원합니다.

Tailwind가 포함된 새 프로젝트 만들기

create astro를 사용하여 Tailwind CSS가 사전 구성된 새 Starlight 프로젝트를 시작하세요.

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
Terminal window
npx astro add tailwind
Terminal window
pnpm astro add tailwind
Terminal window
yarn astro add tailwind

Starlight의 Tailwind 호환성 패키지를 설치합니다.

npm install @astrojs/starlight-tailwind

pnpm add @astrojs/starlight-tailwind

yarn add @astrojs/starlight-tailwind

Astro가 스캐폴딩한 src/styles/global.css 파일의 콘텐츠를 Starlight와의 호환성을 위해 다음 코드로 교체합니다.

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

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

Tailwind CSS 파일을 사용하도록 Starlight 구성을 업데이트합니다.

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Tailwind를 사용한 문서',
      customCss: [
        // Tailwind 기본 스타일의 경로입니다.
        './src/styles/global.css',
      ],
    }),
  ],
  vite: { plugins: [tailwindcss()] },
});

Tailwind로 Starlight 스타일링하기

Starlight는 UI에서 Tailwind 테마 구성 값을 사용합니다.

설정되면 다음 CSS 사용자 정의 속성이 Starlight의 기본 스타일을 재정의합니다.

--color-accent-* — 링크 및 현재 항목 강조 표시에 사용됩니다.
--color-gray-* — 배경색 및 테두리에 사용됩니다.
--font-sans — UI 및 콘텐츠 텍스트에 사용됩니다.
--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);
}

테마

기본 사용자 정의 속성을 변경하여 Starlight의 색상 테마를 제어할 수 있습니다. 이러한 변수는 텍스트 및 배경색에 사용되는 다양한 회색 음영과 링크에 사용되는 강조 색상 및 탐색에서 현재 항목을 강조 표시하는 UI 전체에서 사용됩니다.

색상 테마 편집기

아래 슬라이더를 사용하여 Starlight의 강조 및 회색 색상 팔레트를 수정하세요. 어둡고 밝은 미리보기 영역에는 결과 색상이 표시되며 전체 페이지도 업데이트되어 변경 사항을 미리 확인할 수 있습니다.

대비 수준 옵션을 사용하여 웹 콘텐츠 접근성 가이드라인 색상 대비 표준 중 어느 것을 충족할지 지정합니다.

변경 사항이 만족스러우면 아래 CSS 또는 Tailwind 코드를 복사하여 프로젝트에 사용하세요.

프리셋

대비 수준

AA AAA

강조

색상 269

채도 0.27

회색조

색상 270

채도 0.016

어두운 테마

본문 텍스트는 배경과 대비가 높은 회색 음영으로 표시됩니다. 링크에 색상이 지정됩니다. 콘텐츠 목차와 같은 일부 텍스트는 대비가 낮습니다. 인라인 코드에는 뚜렷한 배경이 있습니다.

사용자 정의 CSS파일에 아래 코드를 추가하여 현재 테마를 프로젝트에 적용하세요.

사이트에 이 테마를 적용하려면 Tailwind CSS 파일의 @theme 블록에 다음 CSS 변수를 추가하세요.