Hagilight 예제

이 페이지는 공유 Astro 컴포넌트를 사용합니다:

© 2026 HagiCode

Starlight 플러그인도 같은 컴포넌트를 페이지 바닥글에 추가합니다.

생성된 404 페이지 열기

플러그인은 언어별 피드를 생성합니다. 기본 영어 RSS 피드와 이 페이지의 한국어 RSS 피드입니다.

공유 컴포넌트

Hagilight는 Astro 및 Starlight 사이트를 위한 재사용 가능한 작은 컴포넌트 모음입니다. 패키지는 별도로 게시되므로 사이트에서 공유 Astro 컴포넌트, Starlight 통합, 또는 둘 다를 선택할 수 있습니다.

Astro 컴포넌트

Astro 페이지나 MDX 문서의 frontmatter에서 컴포넌트를 가져온 다음 다른 컴포넌트처럼 사용하세요:

---
import Copyright from '@hagicode/hagilight/Copyright';
import PromotoBanner from '@hagicode/hagilight/PromotoBanner';
---

<Copyright name="HagiCode" />
<PromotoBanner locale="en-US" />

프로모션 컴포넌트는 공개 Index 피드에서 활성 캠페인을 불러옵니다. 현재 페이지 언어를 사용하여 번역 텍스트를 선택하고, 번역이 없으면 영어로 폴백합니다.

사이트가 제공하는 폴백

원격 캠페인이 활성화되어 있지 않을 때 사이트는 방문자를 위해 자체 현지화된 폴백을 제공할 수 있습니다. 텍스트와 이동 경로는 자신의 사이트에 맞게 유지하세요:

<PromotoBanner
  fallback={{
    id: 'site-news',
    title: '사이트의 새로운 소식',
    description: '최신 릴리스 노트와 제품 업데이트를 읽어보세요.',
    ctaLabel: '소식 보기',
    link: '/news/',
  }}
/>

폴백은 선택 사항입니다. 없으면 캠페인을 사용할 수 없을 때도 페이지에 빈 배너가 남지 않습니다.

Starlight 통합

@hagicode/hagilight-starlight 플러그인은 기본 Starlight 바닥글을 유지하면서 공유 저작권 정보를 추가합니다. 프로모션 배너는 기본적으로 활성화되어 있습니다. 사이트가 바닥글 통합은 유지하되 프로모션을 표시하지 않으려면 비활성화하세요:

import hagilight from '@hagicode/hagilight-starlight';

plugins: [hagilight({ promoto: { enabled: false } })]

데모는 배너를 명시적으로 활성화합니다. 예제 페이지는 스크롤할 콘텐츠가 충분하므로 바닥글이 뷰포트 밖에서 시작되고 페이지 하단에 배너가 보입니다.

AI 공개 frontmatter

데모는 기본적으로 두 공개를 모두 활성화하고 소스 언어로 root를 사용합니다. 페이지의 frontmatter에 선택적 불리언 필드를 추가하여 이러한 기본값을 재정의할 수 있습니다:

---
title: 번역된 가이드
isAITranslation: true
isAIAuthor: true
---

생략한 필드는 플러그인 설정을 상속합니다. 필드를 false로 설정하면 해당 공개만 숨길 수 있습니다:

---
title: AI 작성자 알림이 없는 가이드
isAIAuthor: false
---

이 페이지는 재정의를 보여줍니다. 번역된 en-us 데모 페이지는 두 알림을 모두 상속합니다. 번역 알림은 소스 언어 페이지에서 숨겨지며, 소스 페이지가 있으면 해당 페이지로 연결됩니다. 데모의 콘텐츠 스키마는 aiDisclosureSchema를 통해 Hagilight의 선택적 필드를 포함합니다. 이를 사용하려면 소비 측에도 같은 스키마 확장이 필요합니다.

배너 동작

바닥글이 보이지 않는 동안 배너는 뷰포트 하단 근처에 머무릅니다. 바닥글이 뷰포트에 들어오면 배너는 페이드 아웃되고 포인터 및 키보드 상호작용 가로채기를 멈춥니다. 바닥글이 뷰포트를 벗어나면 닫히지 않은 한 배너가 다시 나타납니다.

방문자는 활성 캠페인을 해제할 수 있습니다. 해제는 해당 캠페인 집합에 대해 브라우저에 기억되며, 캠페인 내용이 바뀌면 다시 표시될 수 있습니다. 닫기 버튼은 넓은 화면과 좁은 화면 모두에서 사용할 수 있습니다.

여러 캠페인을 사용할 수 있을 때 배너는 한 번에 하나의 카드만 표시합니다. 이전/다음 버튼으로 카드 사이를 이동하거나 자동 순환을 일시 중지하세요. 페이지는 브라우저의 모션 줄이기 설정을 존중하여 자동 순환을 비활성화하되 수동 탐색은 유지합니다.

Markdown 예제

이 페이지는 문서 사이트에서 유용한 일반적인 Markdown 패턴도 보여줍니다.

강조 및 링크

텍스트는 굵게, 기울임, 또는 취소선 처리할 수 있습니다. promoto.enabled와 같은 인라인 코드는 본문과 시각적으로 구분됩니다. 링크는 Astro를 가리키거나 이 페이지의 섹션을 가리킬 수 있습니다.

목록

순서 없는 목록은 관련 항목에 유용합니다:

• 컴포넌트는 .astro 파일로 작성됩니다.
• 패키지는 Astro가 컴파일하도록 소스를 게시합니다.
• Starlight 사이트는 프로모션 배너를 제외할 수 있습니다.

순서 있는 목록은 순차 작업에 적합합니다:

1. Astro 및 Starlight와 함께 패키지를 설치합니다.
2. 사이트 설정에 Starlight 플러그인을 추가합니다.
3. 사이트를 빌드하고 생성된 페이지를 검토합니다.

목록은 중첩할 수도 있습니다:

• 패키지 내용
  • Astro 컴포넌트
  • Starlight 재정의
• 예제 사이트
  • 데모 구성
  • 문서 페이지

인용

재사용 가능한 컴포넌트를 특정 사이트의 라우트나 복사본과 독립적으로 유지하세요.

필요할 때 소비 측 사이트가 자체 폴백을 제공할 수 있습니다.

코드 블록

플러그인은 Astro 구성에서 명시적으로 활성화할 수 있습니다:

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

export default defineConfig({
  integrations: [
    starlight({
      title: '내 문서',
      plugins: [hagilight({ promoto: { enabled: true } })],
    }),
  ],
});

JSON 구성 데이터는 별도의 펜스 블록으로 표시할 수 있습니다:

{
  "promoto": {
    "enabled": true
  }
}

표

표를 사용하면 각 패키지의 책임을 한눈에 파악할 수 있습니다:

패키지	용도	주요 항목
@hagicode/hagilight	공유 Astro 컴포넌트	Copyright, PromotoBanner
@hagicode/hagilight-starlight	Starlight 바닥글 통합	hagilight()

배너 컨트롤

컨트롤	동작
닫기	현재 프로모션 집합 해제
이전	이전 활성 캠페인 표시
다음	다음 활성 캠페인 표시
일시 중지	자동 순환 중지

작업 목록

간단한 체크리스트로 문서 변경을 추적할 수 있습니다:

• 공유 컴포넌트 예제를 추가합니다.
• 플러그인 옵션을 문서화합니다.
• 사이트에 현지화된 캠페인 복사본이 있을 때 사이트별 폴백을 추가합니다.

가로선

---

빌드 및 패키징

워크스페이스에는 데모 사이트와 두 패키지가 포함됩니다. 데모는 로컬 개발 중에 동일한 워크스페이스 패키지를 사용하며, 설치된 패키지 검사는 생성된 tarball을 사용해 임시 소비자를 빌드합니다.

패키지 검사는 내보낸 각 컴포넌트와 필요한 브라우저 측 소스가 게시 아카이브에 존재하는지 확인합니다. 설치된 빌드는 두 플러그인 상태도 검사합니다. 활성 빌드에는 배너 마운트 지점과 스크립트가 포함되고, 비활성 빌드는 기존 바닥글을 유지하며 프로모션 마크업과 코드를 생략합니다.

이러한 검사는 누락된 파일을 조기에 발견하는 데 도움이 됩니다. 또한 나중에 컴포넌트를 변경하거나 데모 구성을 업데이트하는 유지 관리자에게 예상 동작을 명확히 보여줍니다.

질문 및 다음 단계

이미 자체 Starlight 바닥글을 제공하는 사이트에서 Hagilight를 사용할 때는 Starlight가 바닥글 재정의를 하나만 허용한다는 점을 기억하세요. 두 재정의를 동시에 등록하는 대신, 공유 바닥글 컴포넌트를 사이트 자체의 재정의에 포함하세요.

Docs 사이트에는 자체 프로모션 배너와 폴백 콘텐츠가 있습니다. Docs가 별도의 변경으로 공유 컴포넌트를 채택하기 전까지는 해당 사이트에서 두 구현을 모두 활성화하면 배너가 중복 표시될 수 있습니다.

새로운 Astro 사이트의 경우 공유 컴포넌트 가져오기부터 시작하고, Starlight를 사용할 때만 Starlight 플러그인을 추가하세요. 캠페인 콘텐츠, 현지화된 폴백 복사본, 사이트 탐색은 재사용 가능한 패키지에 하드코딩하지 말고 소비 측 사이트에 두세요.