ヘッダー右側アイテム

サイトヘッダー右側のクラスタ(検索・テーマ・言語切替など)をデータ駆動の配列で構成する。

ヘッダーの右側 — 検索、外観メニュー、言語スイッチャー、バージョンスイッチャー、GitHub リンク、Design Token / AI Chat トリガー — は headerRightItems という 1 つの配列フィールドからレンダリングされます。各エントリは discriminated union で、配列の順番どおりに描画されます。

デフォルト設定

export default defineConfig(
  zudoDoc({
    // ...
    githubUrl: "https://github.com/zudolab/zudo-doc",
    headerRightItems: [
      { type: "trigger", trigger: "design-token-panel" },
      { type: "trigger", trigger: "ai-chat" },
      { type: "component", component: "version-switcher" },
      { type: "component", component: "github-link" },
      { type: "component", component: "theme-toggle" },
      { type: "component", component: "search" },
      { type: "component", component: "language-switcher" },
    ],
  }),
);

アイテム種別

component

組み込みの UI 要素を参照します。多くは対応する機能フラグが無効だと自動的にスキップされますが、search にはフラグによる制御がありません。

{ type: "component", component: "github-link" }

機能を無効化すればエントリは黙って除外されるので、配列に残したままでも問題ありません。search には専用の機能フラグがありません — レンダラーは常に利用可能で、表示するかどうか・どの位置に表示するかは配列内の記述だけで決まります。

trigger

組み込みのモーダルやパネルを開きます。

{ type: "trigger", trigger: "ai-chat" }

design-token-panel トリガーボタンは window に toggle-design-token-panel カスタムイベントをディスパッチします。zdtpパネル（@takazudo/zdtp）はこのイベントをネイティブに受け取るため、追加の配線は不要です。

link

任意の外部/内部リンクをアイコン付きで描画します。

{
  type: "link",
  href: "https://discord.example",
  ariaLabel: "Discord",
  icon: "github", // only "github" is bundled today
}

外部 URL は自動的に新しいタブで開きます。

html

任意のマークアップを差し込むためのエスケープハッチです。

{ type: "html", html: '<span class="text-caption">beta</span>' }

文字列がそのまま出力されるため、使いどころは限定してください。

カスタマイズ例

GitHub アイコンをあなたのリポジトリへ向ける

zfb.config.tsのzudoDoc({...})でトップレベルの githubUrl を書き換えるだけで済みます。github-link コンポーネントはこの値を読むので、配列側に URL を書き足す必要はありません。

export default defineConfig(
  zudoDoc({
    githubUrl: "https://github.com/your-org/your-repo",
  }),
);

githubUrl: false を指定すると、配列を編集せずにアイコンだけ消せます。

アイテムを外す

機能フラグでの非表示ではなく、配列から該当エントリを削除してください。たとえば AI chat トリガーを隠すなら:

headerRightItems: [
  { type: "trigger", trigger: "design-token-panel" },
  // { type: "trigger", trigger: "ai-chat" },  // removed
  { type: "component", component: "version-switcher" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "language-switcher" },
],

カスタムリンクを追加する

headerRightItems: [
  // ...existing items
  {
    type: "link",
    href: "https://discord.gg/your-server",
    ariaLabel: "Discord",
    icon: "github", // until more icons are bundled
  },
],

カスタムレンダラーを追加する

プロジェクト固有のコンポーネント名は chromeBindings.headerRightComponents で解決します。型付きの設定手順全体は Host Chrome Bindings を参照してください。クライアント island に対応する静的な登録経路も用意していない限り、レンダラーは SSR 表示用として扱います。

登録済み island の props が現在のページではなくブラウザーセッションに属する場合は、遷移前から存在する island 自体か、persist されたヘッダー内の祖先要素に data-zd-props-preserve を付けます。オプトアウトは遷移前から存在する DOM を基準に判定され、対象 island のシリアライズ済み props は置き換えられず、remount 対象にもなりません。persist されたヘッダー自体に属性を付けると配下の全 island がオプトアウトされるため、遷移先ページの props を受け取るべき island には付けないでください。

外観メニューのカスタマイズ

組み込みのtheme-toggleは標準ヘッダーの外観メニューです。同じメニューを別の場所へ置く場合は、公開@takazudo/zudo-doc/theme-toggleサブパスからThemeToggleをインポートし、固定ターゲットのサーバー境界で合成します。

import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";

エクスポートされる ThemeToggle は、コンパクトな <button> と Light / Dark / System のメニューを描画します。太陽、月、モニターのアイコンは選択中の設定を表します。System が選択されている場合、デバイス設定でページの実効ライト/ダーク表示が変わっても、モニターアイコンのままです。defaultMode は引き続きライト/ダークのフォールバックで、respectPrefersColorScheme は初回訪問時に System を選ぶかどうかを制御します。メニューとアクセシビリティ用の文字列は labels プロップでローカライズできます。好きな場所に配置してその周りに UI を組み合わせることはできますが、ボタンのマークアップとアイコンは固定です — インポートはパッケージの外観メニューを再利用する(そして後述の衝突を避ける)ためのものであって、見た目を変更するためのものではありません。異なるメニューのマークアップやアイコンが必要な場合は、自前のコンポーネントを作り、パッケージの island マーカーを主張しないように ThemeToggle 以外の名前を付けてください。

なぜパッケージの island をインポートするのか

各クライアントエントリーには一意のアイランドidentityが必要です。別のソースファイルがThemeToggleを名乗る状態は、無害な警告やスキャン順による上書きではなくエラーです。パッケージのエントリーを再利用します。別のメニューを作る場合は、クライアントエントリーに異なるエクスポート名を付け、その1つのターゲットをサーバー境界へ静的にインポートします。displayNameの設定や重複するローカルshimでパッケージのアイランドを置き換えないでください。

このリポジトリはnode scripts/check-client-export-names.mjsでエントリーグラフを検証し、ビルド前にidentityの重複を拒否します。virtual bindings内のレンダラーだけでは、クライアントエントリーへのスキャナー到達性を保証できません。Custom Componentsの具体的な静的ルートインポートに従ってください。

並び順

配列に書いた順にレンダリングされます。クラスタは右寄せなので、最初のエントリがナビ寄り、末尾のエントリがビューポート端寄りに配置されます。