재정의 참조

Starlight의 components 구성 옵션에 대체 컴포넌트에 대한 경로를 제공하여 Starlight의 내장 컴포넌트를 재정의할 수 있습니다. 이 페이지에는 재정의할 수 있는 모든 컴포넌트와 기본 구현에 대한 Github 링크가 나열되어 있습니다.

컴포넌트 재정의 가이드에서 자세히 알아보세요.

컴포넌트 속성

사용자 정의 컴포넌트의 타입을 설정하기 위해 Starlight로부터 Props 타입을 가져옵니다.

---
import type { Props } from '@astrojs/starlight/props';

const { hasSidebar } = Astro.props;
//      ^ type: boolean
---

이는 Astro.props에 접근할 때 자동완성과 타입을 제공합니다.

속성

Starlight는 사용자 정의 컴포넌트에 다음 속성들을 전달합니다.

`dir`

타입: 'ltr' | 'rtl'

페이지 작성 방향입니다.

`lang`

타입: string

이 페이지의 로케일에 대한 BCP-47 언어 태그입니다. 예: en, zh-CN 또는 pt-BR

`locale`

타입: string | undefined

언어가 제공되는 기본 경로입니다. 루트 로케일 슬러그의 경우 undefined입니다.

`slug`

타입: string

콘텐츠 파일 이름에서 생성된 이 페이지의 슬러그입니다.

`id`

타입: string

콘텐츠 파일 이름을 기반으로 하는 이 페이지의 고유 ID입니다.

`isFallback`

타입: true | undefined

이 페이지가 현재 언어로 번역되지 않고 기본 로케일의 대체 콘텐츠를 사용하는 경우 true입니다. 다국어 사이트에서만 사용됩니다.

`entryMeta`

타입: { dir: 'ltr' | 'rtl'; lang: string }

페이지 콘텐츠의 로케일 메타데이터입니다. 페이지가 대체 콘텐츠를 사용하는 경우 최상위 로케일 값과 다를 수 있습니다.

`entry`

현재 페이지에 대한 Astro 콘텐츠 컬렉션 항목입니다. entry.data는 현재 페이지에 대한 프론트매터 값을 포함합니다.

entry: {
  data: {
    title: string;
    description: string | undefined;
    // etc.
  }
}

Astro 컬렉션 엔트리 타입 참조에서 이 객체의 형태에 대해 자세히 알아보세요.

`sidebar`

타입: SidebarEntry[]

페이지에 대한 사이트 탐색 사이드바 엔트리입니다.

`hasSidebar`

타입: boolean

이 페이지에 사이드바를 표시할지 여부입니다.

`pagination`

타입: { prev?: Link; next?: Link }

활성화된 경우 사이드바의 이전 및 다음 페이지로 이동하는 링크를 표시합니다.

`toc`

타입: { minHeadingLevel: number; maxHeadingLevel: number; items: TocItem[] } | undefined

활성화된 경우 이 페이지의 목차를 표시합니다.

`headings`

타입: { depth: number; slug: string; text: string }[]

현재 페이지에서 추출된 모든 Markdown 제목의 배열입니다. Starlight의 구성 옵션을 준수하는 콘텐츠 목차 컴포넌트를 생성하기 위해서는 toc를 사용하세요.

`lastUpdated`

타입: Date | undefined

활성화된 경우 이 페이지가 마지막으로 업데이트된 날짜를 나타내기 위해 JavaScript Date객체가 사용됩니다.

`editUrl`

타입: URL | undefined

활성화된 경우 이 페이지를 편집할 수 있는 주소를 나타내기 위해 URL 객체가 사용됩니다.

컴포넌트

헤드

이 컴포넌트들은 각 페이지의 <head> 요소 내에 렌더링됩니다. 또한, 반드시 <head> 내에서 사용하는 것이 허용되는 요소만 포함해야 합니다.

`Head`

기본 컴포넌트: Head.astro

각 페이지의 <head> 내에서 렌더링되는 컴포넌트입니다. <title>, <meta charset="utf-8">를 포함하여 중요한 태그들이 포함합니다.

최후의 수단으로 이 컴포넌트를 재정의합니다. 가능하면 Starlight 구성의 head 옵션을 사용하는 것이 좋습니다.

`ThemeProvider`

기본 컴포넌트: ThemeProvider.astro

다크/라이트 테마를 설정하기 위해 <head> 내에서 렌더링되는 컴포넌트입니다. 기본 구현에는 <ThemeSelect />에서 사용되는 인라인 스크립트와 <template>이 포함되어 있습니다.

접근성

`SkipLink`

기본 컴포넌트: SkipLink.astro

<body> 내부에서 첫 번째 요소로 렌더링되며 메인 페이지의 콘텐츠로 이동하는 접근성을 위한 컴포넌트입니다. 기본적으로 키보드의 탭을 통해 선택하기 전까지는 숨겨져 있습니다.

레이아웃

이 컴포넌트들은 Starlight 컴포넌트들을 배치하고 다양한 중단점에서 보이는 모습을 관리합니다. 이 컴포넌트들을 재정의하면 상당한 복잡성이 발생하므로, 가능하면 하위 수준의 컴포넌트를 재정의하는 것이 좋습니다.

`PageFrame`

기본 컴포넌트: PageFrame.astro

대부분의 페이지 콘텐츠를 감싸는 레이아웃 컴포넌트입니다. 기본적으로 header-sidebar-main 레이아웃을 설정하고 슬롯으로 명명된 header와 sidebar 및 메인 콘텐츠에 대한 기본 슬롯을 포함합니다. 또한, 작은 (모바일) 뷰포트에서 사이드바 탐색 토글을 지원하기 위해 <MobileMenuToggle />를 렌더링합니다.

`MobileMenuToggle`

기본 컴포넌트: MobileMenuToggle.astro

작은 (모바일) 뷰포트에서 사이드바 탐색 토글을 수행하는 <PageFrame> 내부에서 렌더링되는 컴포넌트입니다.

`TwoColumnContent`

기본 컴포넌트: TwoColumnContent.astro

메인 콘텐츠 열과 오른쪽 사이드바 (목차)를 감싸는 레이아웃 컴포넌트입니다. 기본적으로 작은 뷰포트에서 하나의 열로 이루어진 레이아웃과 큰 뷰포트에서 두 개의 열로 이루어진 레이아웃 간 전환을 처리합니다.

헤더

Starlight의 상단 탐색 바를 렌더링하는 컴포넌트입니다.

`Header`

기본 컴포넌트: Header.astro

Header 컴포넌트는 모든 페이지 상단에 표시됩니다. 기본적으로 <SiteTitle />, <Search />, <SocialIcons />, <ThemeSelect />, 와 <LanguageSelect />를 표시합니다.

`SiteTitle`

기본 컴포넌트: SiteTitle.astro

사이트 제목을 렌더링하기 위해 사이트 헤더 시작 부분에 렌더링되는 컴포넌트입니다. 기본적으로 Starlight 구성에 정의된 로고를 렌더링하는 논리가 포함합니다.

`Search`

기본 컴포넌트: Search.astro

Starlight의 검색 UI를 렌더링하기 위해 사용되는 컴포넌트입니다. 기본적으로 헤더의 버튼과 클릭하면 Pagefind의 UI를 불러오는 검색 모달을 나타내는 코드가 포함되어 있습니다.

`SocialIcons`

기본 컴포넌트: SocialIcons.astro

사이트 헤더에 렌더링되며 소셜 아이콘 링크를 포함하는 컴포넌트입니다. 기본적으로 아이콘과 링크를 렌더링하기 위해 Starlight 구성에서 social 옵션을 사용합니다.

`ThemeSelect`

기본 컴포넌트: ThemeSelect.astro

사용자가 선호하는 색 구성표를 선택할 수 있도록 사이트 헤더에 렌더링되는 컴포넌트입니다.

`LanguageSelect`

기본 컴포넌트: LanguageSelect.astro

사용자가 다른 언어로 전환할 수 있도록 사이트 헤더에 렌더링되는 컴포넌트입니다.

전역 사이드바

Starlight의 전역 사이드바에는 메인 사이트 탐색이 포함되어 있습니다. 좁은 뷰포트에서는 드롭다운 메뉴 뒤에 숨겨져 있습니다.

`Sidebar`

기본 컴포넌트: Sidebar.astro

전역 탐색이 포함된 페이지 콘텐츠 앞에 렌더링되는 컴포넌트입니다. 기본적으로 충분히 넓은 뷰포트에서는 사이드바로 나타나고, 작은 (모바일) 뷰포트에서는 드롭다운 메뉴로 나타납니다. 또한, 모바일 메뉴 내부에 추가 항목을 표시하기 위해 <MobileMenuFooter />를 렌더링합니다.

`MobileMenuFooter`

기본 컴포넌트: MobileMenuFooter.astro

모바일 드롭다운 메뉴 하단에 렌더링되는 컴포넌트입니다. 기본적으로 <ThemeSelect />와 <LanguageSelect />를 렌더링합니다.

페이지 사이드바

Starlight의 페이지 사이드바는 현재 페이지의 하위 제목을 간략하게 설명하는 목차를 표시합니다. 좁은 뷰포트에서는 고정된 드롭다운 메뉴로 축소됩니다.

`PageSidebar`

기본 컴포넌트: PageSidebar.astro

목차를 나타내기 위해 메인 페이지의 콘텐츠 앞에 렌더링되는 컴포넌트입니다. 기본적으로 <TableOfContents />와 <MobileTableOfContents />를 렌더링합니다.

`TableOfContents`

기본 컴포넌트: TableOfContents.astro

더 넓은 뷰포트에서 현재 페이지의 목차를 렌더링하는 컴포넌트입니다.

`MobileTableOfContents`

기본 컴포넌트: MobileTableOfContents.astro

작은 (모바일) 뷰포트에서 현재 페이지의 목차를 렌더링하는 컴포넌트입니다.

콘텐츠

이 컴포넌트들은 페이지 콘텐츠의 메인 열에 렌더링됩니다.

`Banner`

기본 컴포넌트: Banner.astro

각 페이지 상단에 렌더링되는 배너 컴포넌트입니다. 기본적으로 페이지의 banner 프론트매터 속성을 사용하여 렌더링 여부를 결정합니다.

`ContentPanel`

기본 컴포넌트: ContentPanel.astro

메인 콘텐츠 열의 섹션을 감싸는 레이아웃 컴포넌트입니다.

`PageTitle`

기본 컴포넌트: PageTitle.astro

현재 페이지의 <h1> 요소를 포함하는 컴포넌트입니다. 기본 구현과 같이 <h1> 요소에 id="_top"을 설정해야 합니다.

`FallbackContentNotice`

기본 컴포넌트: FallbackContentNotice.astro

현재 언어에 대한 번역이 제공되지 않는 페이지에서 사용자에게 표시되는 알림입니다. 다국어 사이트에서만 사용됩니다.

`Hero`

기본 컴포넌트: Hero.astro

프론트매터에서 hero를 설정했을 때, 페이지 상단에 렌더링되는 컴포넌트입니다. 기본적으로 큰 제목, 태그라인, 클릭 유도 문구 링크와 선택적 이미지를 표시합니다.

`MarkdownContent`

기본 컴포넌트: MarkdownContent.astro

각 페이지의 메인 콘텐츠 주위에 렌더링되는 컴포넌트입니다. 기본적으로 마크다운 콘텐츠에 적용할 기본 스타일을 설정합니다.

바닥글

이 컴포넌트들은 페이지 콘텐츠의 메인 열 하단에 렌더링됩니다.

`Footer`

기본 컴포넌트: Footer.astro

각 페이지 하단에 표시되는 바닥글 컴포넌트입니다. 기본적으로 <LastUpdated />, <Pagination />, 그리고 <EditLink />를 표시합니다.

`LastUpdated`

기본 컴포넌트: LastUpdated.astro

마지막 업데이트 날짜를 표시하기 위해 페이지 바닥글에 렌더링되는 컴포넌트입니다.

`EditLink`

기본 컴포넌트: EditLink.astro

페이지를 편집할 수 있는 링크를 표시하기 위해 페이지 바닥글에 렌더링되는 컴포넌트입니다.

`Pagination`

기본 컴포넌트: Pagination.astro

Component rendered in the page footer to display navigation arrows between previous/next pages.

이전/다음 페이지 사이에 탐색 화살표를 표시하기 위해 페이지 바닥글에 렌더링되는 컴포넌트입니다.