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 の任意フィールドを含んでいます。利用するには消費側でも同じスキーマ拡張が必要です。

バナーの動作

フッターが表示されていない間、バナーはビューポートの下部近くに留まります。フッターがビューポートに入ると、バナーはフェードアウトし、ポインターやキーボードの操作の傍受をやめます。フッターがビューポートを離れると、閉じられていない限りバナーが再び表示されます。

訪問者は有効なキャンペーンを閉じられます。その却下はそのキャンペーンセットについてブラウザーに記憶され、キャンペーン内容が変わった場合は再表示されます。閉じるボタンは幅の広い画面でも狭い画面でも利用できます。

複数のキャンペーンが利用可能な場合、バナーは一度に 1 枚のカードを表示します。前へ・次へボタンでカード間を移動するか、自動ローテーションを一時停止できます。ページはブラウザーのモーション削減設定を尊重し、自動ローテーションを無効にしつつ手動ナビゲーションを残します。

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()

バナーの操作

操作	動作
閉じる	現在のプロモーションセットを閉じる
前へ	前の有効キャンペーンを表示
次へ	次の有効キャンペーンを表示
一時停止	自動ローテーションを停止

タスクリスト

シンプルなチェックリストでドキュメントの変更を追跡できます：

• 共有コンポーネントの例を追加する。
• プラグインオプションを文書化する。
• サイトがローカライズしたキャンペーン文案を持つ場合、サイト固有のフォールバックを追加する。

水平線

---

ビルドとパッケージ化

ワークスペースにはデモサイトと 2 つのパッケージが含まれます。デモはローカル開発中に同じワークスペースパッケージを使用し、インストール済みパッケージのチェックは生成された tarball を使って一時的な消費側をビルドします。

パッケージチェックは、エクスポートされた各コンポーネントとその必須のブラウザー側ソースが公開アーカイブに存在することを確認します。インストール済みビルドは両方のプラグイン状態も確認します。有効なビルドにはバナーのマウント位置とスクリプトが含まれ、無効なビルドは既存のフッターを維持しプロモーションのマークアップとコードを省略します。

これらのチェックは欠落したファイルを早期に発見するのに役立ちます。また、後でコンポーネントを変更したりデモ設定を更新したりするメンテナーに期待される動作を分かりやすく示します。

質問と次のステップ

すでに独自の Starlight フッターを提供しているサイトで Hagilight を使う場合、Starlight はフッターの上書きを 1 つしか許さないことを覚えておいてください。2 つの上書きを同時に登録するのではなく、共有フッターコンポーネントをサイト独自の上書きに組み込んでください。

Docs サイトには独自のプロモーションバナーとフォールバックコンテンツがあります。Docs が別の変更で共有コンポーネントを採用するまで、そのサイトで両方の実装を有効にするとバナーが重複して表示される可能性があります。

新しい Astro サイトの場合は、共有コンポーネントのインポートから始め、Starlight を使う場合にのみ Starlight プラグインを追加してください。キャンペーン内容、ローカライズされたフォールバック文案、サイトナビゲーションは、再利用可能なパッケージに埋め込むのではなく消費側サイトに置いてください。