Skip to content

Latest commit

 

History

History
291 lines (216 loc) · 8.54 KB

css-and-tailwind.mdx

File metadata and controls

291 lines (216 loc) · 8.54 KB
title description
CSS & 스타일링
맞춤형 CSS로 Starlight 사이트의 스타일을 지정하거나 Tailwind CSS와 통합하는 방법을 알아보세요.

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

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

사용자 정의 CSS 스타일

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

  1. src/ 디렉터리에 CSS 파일을 추가합니다. 예를 들어, 아래 코드를 통해 페이지 제목을 더 넓게 만들고, 더 큰 텍스트를 사용할 수 있습니다.

    /* src/styles/custom.css */
:root {
	--sl-content-width: 50rem;
	--sl-text-5xl: 3.5rem;
}

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

    // 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',
			],
		}),
	],
});

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

Tailwind CSS

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

Starlight Tailwind 플러그인은 다음 구성을 적용합니다.

  • Starlight의 다크 모드와 작동하도록 Tailwind의 dark: 변형을 구성합니다.
  • Starlight UI에서 Tailwind 테마 색상 및 글꼴을 사용합니다.
  • Tailwind의 Preflight 초기화 스타일을 비활성화하는 동시에 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를 추가하려면 다음 단계를 따르세요.

  1. Astro의 Tailwind 통합 추가

    npx astro add tailwind
    pnpm astro add tailwind
    yarn astro add tailwind

  2. Starlight Tailwind 플러그인을 설치하세요.

    npm install @astrojs/starlight-tailwind
    pnpm add @astrojs/starlight-tailwind
    yarn add @astrojs/starlight-tailwind

  3. src/tailwind.css 파일과 같은 Tailwind의 기본 스타일에 대한 CSS 파일을 만드세요.

    /* src/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

  4. Tailwind 기반 스타일을 사용하고 기본 스타일을 비활성화하려면 Astro 구성 파일을 업데이트하세요.

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

export default defineConfig({
	integrations: [
		starlight({
			title: 'Tailwind를 사용한 문서',
			customCss: [
				// Tailwind 기반 스타일 경로
				'./src/tailwind.css',
			],
		}),
		tailwind({
			// 기본 스타일을 비활성화합니다.
			applyBaseStyles: false,
		}),
	],
});

  5. tailwind.config.mjs 파일에 Starlight Tailwind 플러그인을 추가하세요.

    // tailwind.config.mjs
import starlightPlugin from '@astrojs/starlight-tailwind';

/** @type {import('tailwindcss').Config} */
export default {
	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
	plugins: [starlightPlugin()],
};

Tailwind로 Starlight 스타일링하기

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

설정된 경우 다음 옵션이 Starlight의 기본 스타일을 재정의합니다.

  • colors.accent — 링크 및 현재 항목 강조에 사용됩니다.
  • colors.gray — 배경색과 테두리에 사용됩니다.
  • fontFamily.sans — UI 및 콘텐츠 텍스트에 사용됩니다.
  • fontFamily.mono — 코드 예제에 사용됩니다.
// tailwind.config.mjs
import starlightPlugin from '@astrojs/starlight-tailwind';
import colors from 'tailwindcss/colors';

/** @type {import('tailwindcss').Config} */
export default {
	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
	theme: {
		extend: {
			colors: {
				// 선호하는 강조 색상입니다. Indigo는 Starlight의 기본값에 가장 가깝습니다.
				accent: colors.indigo,
				// 선호하는 회색조입니다. Zinc는 Starlight의 기본값에 가장 가깝습니다.
				gray: colors.zinc,
			},
			fontFamily: {
				// 선호하는 텍스트 글꼴입니다. Starlight는 기본적으로 시스템 글꼴 스택을 사용합니다.
				sans: ['"Atkinson Hyperlegible"'],
				// 선호하는 코드 글꼴입니다. Starlight는 기본적으로 시스템 고정 폭 글꼴을 사용합니다.
				mono: ['"IBM Plex Mono"'],
			},
		},
	},
	plugins: [starlightPlugin()],
};

테마

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

색상 테마 편집기

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

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

import ThemeDesigner from '~/components/theme-designer.astro';

<ThemeDesigner labels={{ presets: { label: '프리셋', ocean: '오션', forest: '숲', oxide: '옥사이드', nebula: '성운', default: '기본값', random: '무작위', }, editor: { accentColor: '강조', grayColor: '회색조', hue: '색상', chroma: '채도', pickColor: '색상 선택', }, preview: { darkMode: '어두운 테마', lightMode: '밝은 테마', bodyText: '본문 텍스트는 배경과 대비가 높은 회색 음영으로 표시됩니다.', linkText: '링크에 색상이 지정됩니다.', dimText: '콘텐츠 목차와 같은 일부 텍스트는 대비가 낮습니다.', inlineCode: '인라인 코드에는 뚜렷한 배경이 있습니다.', }, }}

<Fragment slot="css-docs">
	[사용자 정의 CSS파일](#사용자-정의-css-스타일)에 아래 코드를 추가하여 현재 테마를 프로젝트에 적용하세요.
</Fragment>
<Fragment slot="tailwind-docs">
	아래 [Tailwind 구성 파일](#tailwind로-starlight-스타일링하기)의 예시는 `theme.extend.colors`에서 사용할 `accent` 및 `gray` 색상 팔레트를 포함합니다.
</Fragment>