컴포넌트

컴포넌트를 사용하면 쉽고 일관되게 UI 조각이나 스타일을 재사용할 수 있습니다. 링크 카드나 YouTube 삽입 등을 예로 들 수 있습니다. Starlight는 MDX 파일에서 컴포넌트 사용을 지원하며 사용할 수 있는 몇 가지 공통 컴포넌트를 제공합니다.

Astro 문서에서 컴포넌트 구축에 대해 자세히 알아보세요.

컴포넌트 사용

MDX 파일에서 컴포넌트를 가져온 다음 JSX 태그로 렌더링하여 사용할 수 있습니다. 이는 HTML 태그처럼 보이지만 import 문에 있는 이름과 일치하는 대문자로 시작합니다.

src/content/docs/example.mdx

---
title: 내 문서에 오신 것을 환영합니다
---

import SomeComponent from '~/components/SomeComponent.astro';
import AnotherComponent from '~/components/AnotherComponent.astro';

<SomeComponent prop="어떤 값" />

<AnotherComponent>
  컴포넌트에는 **중첩된 콘텐츠**가 포함될 수도 있습니다.
</AnotherComponent>

Starlight는 Astro로 구동되므로 지원되는 UI 프레임워크(React, Preact, Svelte, Vue, Solid, Lit 및 Alpine)로 빌드된 컴포넌트를 MDX 파일에 추가할 수 있습니다. Astro 문서에서 MDX에서 컴포넌트 사용에 대해 자세히 알아보세요.

Starlight 스타일과의 호환성

Starlight는 요소 사이에 여백을 추가하는 등 Markdown 콘텐츠에 기본 스타일을 적용합니다. 이러한 스타일이 컴포넌트의 모양과 충돌하는 경우 컴포넌트에 not-content 클래스를 추가하여 비활성화하세요.

src/components/Example.astro

<div class="not-content">
  <p>Starlight의 기본 콘텐츠 스타일에 영향을 받지 않습니다.</p>
</div>

내장된 컴포넌트

Starlight는 일반적인 문서 사용 사례를 위한 몇 가지 내장 컴포넌트를 제공합니다. 이러한 컴포넌트는 @astrojs/starlight/components 패키지를 통해 사용할 수 있습니다.

탭

<Tabs> 및 <TabItem> 컴포넌트를 사용하여 탭 인터페이스를 표시할 수 있습니다. 각 <TabItem>은 사용자에게 보여줄 label을 반드시 포함해야합니다.

src/content/docs/example.mdx

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

<Tabs>
  <TabItem label="별">시리우스, 베가, 베텔게우스</TabItem>
  <TabItem label="달">이오, 유로파, 가니메데</TabItem>
</Tabs>

위 코드는 페이지에 아래와 같은 탭을 생성합니다.

별

시리우스, 베가, 베텔게우스

달

이오, 유로파, 가니메데

카드

<Card> 컴포넌트를 사용하면 Starlight 스타일의 상자에 콘텐츠를 표시할 수 있습니다. 공간이 충분할 때 카드를 나란히 표시하려면 <CardGrid> 컴포넌트로 여러 카드를 감싸세요.

<Card> 컴포넌트에는 title 속성이 반드시 필요하며 선택적으로 Starlight 내장 아이콘 중 하나의 이름으로 설정된 icon 속성을 포함할 수 있습니다.

src/content/docs/example.mdx

import { Card, CardGrid } from '@astrojs/starlight/components';

<Card title="확인">강조하고 싶은 흥미로운 콘텐츠.</Card>

<CardGrid>
  <Card title="별" icon="star">
    시리우스, 베가, 베텔게우스
  </Card>
  <Card title="달" icon="moon">
    이오, 유로파, 가니메데
  </Card>
</CardGrid>

위 코드는 페이지에 아래와 같은 요소들을 생성합니다.

확인

강조하고 싶은 흥미로운 콘텐츠.

별

시리우스, 베가, 베텔게우스

달

이오, 유로파, 가니메데

팁

홈 페이지에서 프로젝트의 주요 기능을 보여주기 위해 카드 그리드를 사용하세요. 카드의 두 번째 열을 수직으로 이동시켜 시각적 흥미를 더하려면 stagger 속성을 추가하세요.

<CardGrid stagger>
  <!-- 카드 -->
</CardGrid>

링크 카드

다른 페이지로 이동하는 눈에 띄는 링크를 만들기 위해 <LinkCard> 컴포넌트를 사용하세요.

<LinkCard> 컴포넌트에는 title과 href 속성이 필요합니다. 짧은 description이나 target과 같은 기타 링크 속성을 선택적으로 포함할 수 있습니다.

공간이 충분할 때, 카드를 나란히 표시하기 위해 여러 <LinkCard> 컴포넌트를 <CardGrid>에 그룹화하세요.

src/content/docs/example.mdx

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<LinkCard
  title="Starlight 사용자 정의"
  description="사용자 정의 스타일, 글꼴 등을 사용하여 나만의 Starlight 사이트를 만드는 방법을 알아보세요."
  href="/ko/guides/customization/"
/>

<CardGrid>
  <LinkCard
    title="마크다운으로 콘텐츠 작성"
    href="/ko/guides/authoring-content/"
  />
  <LinkCard title="컴포넌트" href="/ko/guides/components/" />
</CardGrid>

위 코드는 페이지에 아래와 같은 요소들을 생성합니다.

Starlight 사용자 정의 사용자 정의 스타일, 글꼴 등을 사용하여 나만의 Starlight 사이트를 만드는 방법을 알아보세요.

마크다운으로 콘텐츠 작성

컴포넌트

아이콘

Starlight는 <Icon> 컴포넌트를 사용하여 콘텐츠에 표시할 수 있는 공통 아이콘 세트를 제공합니다.

각 <Icon> 컴포넌트에는 name 속성이 필요하며 선택적으로 label, size 및 color 속성을 포함할 수 있습니다.

src/content/docs/example.mdx

import { Icon } from '@astrojs/starlight/components';

<Icon name="star" color="goldenrod" size="2rem" />

위 코드는 페이지에 아래와 같은 아이콘을 생성합니다.

모든 아이콘

사용 가능한 모든 아이콘 목록이 관련 이름과 함께 아래에 표시됩니다. 아이콘을 클릭하면 해당 아이콘 컴포넌트의 코드를 복사할 수 있습니다.

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

코드

예를 들어 파일, 데이터베이스 또는 API와 같은 외부 소스에서 오는 데이터를 렌더링하기 위해 Markdown 코드 블록을 사용할 수 없는 경우 <Code> 컴포넌트를 사용하여 구문 강조 코드를 렌더링합니다.

<Code>가 지원하는 props에 대한 자세한 내용은 Expressive Code “Code Component” 문서를 참조하세요.

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';

export const exampleCode = `console.log('This could come from a file or CMS!');`;
export const fileName = 'example.js';
export const highlights = ['file', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

위 코드는 페이지에 다음을 생성합니다.

example.js

console.log('This could come from a file or CMS!');

가져온 코드

Vite의 ?raw 가져오기 접미사를 사용하여 코드 파일을 문자열로 가져옵니다. 그런 다음 가져온 문자열을 <Code> 컴포넌트에 전달하여 페이지에 포함할 수 있습니다.

src/content/docs/example.mdx

import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />

위 코드는 페이지에 다음을 생성합니다.

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />