ヘッダー右側アイテム

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

ヘッダーの右側 — 検索、テーマ切替、言語スイッチャー、バージョンスイッチャー、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", // 現在同梱されているアイコンは "github" のみ
}

外部 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" },  // 削除
  { type: "component", component: "version-switcher" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "language-switcher" },
],

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

headerRightItems: [
  // ...既存のアイテム
  {
    type: "link",
    href: "https://discord.gg/your-server",
    ariaLabel: "Discord",
    icon: "github", // 他アイコン同梱までの暫定
  },
],

テーマ切替のカスタマイズ

組み込みの theme-toggle コンポーネントでたいていのサイトは事足ります。それでも、トグルを独自の場所に配置したい、自前の island ラッパーに組み込みたい、あるいは @takazudo/zudo-doc/theme バレル(React 解決の落とし穴があります — 後述)を避けたいといった理由で、プロジェクト内に 自前の ThemeToggle を持ち続ける場合があります。いずれの場合も、ローカルにコンポーネントを手でコピーするのではなく、専用の @takazudo/zudo-doc/theme-toggle サブパスから ThemeToggle をインポートしてください。

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

エクスポートされる ThemeToggle は、自前の <button> と組み込みの太陽/月アイコンを描画し、受け取るプロップは defaultMode("light" または "dark")の 1 つだけです。好きな場所に配置してその周りに UI を組み合わせることはできますが、ボタンのマークアップとアイコンは固定です — インポートはパッケージのトグルを再利用する(そして後述の衝突を避ける)ためのものであって、見た目を変えるためのものではありません。本当に異なるトグルのマークアップやアイコンが必要な場合は、自前のコンポーネントを作り、パッケージの island マーカーを主張しないように ThemeToggle 以外の名前を付けてください。

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

zfb は(0.1.0-next.39 以降)npm の dist/ に同梱された "use client" モジュールをスキャンします。@takazudo/zudo-doc はスキャナから見える ThemeToggle island を同梱しています。同じ名前のローカル ThemeToggle を手でコピーすると、zfb は ThemeToggle という island マーカーを主張するコンポーネントを 2 つ 検出し、ビルドのたびに衝突警告を出します:

⚠ island marker name collision: "ThemeToggle" is produced by two different source files —
keeping <consumer>/src/components/theme-toggle.tsx and dropping
<pkg>/@takazudo/zudo-doc/dist/theme-toggle/index.js. ...

この警告は無害です — ローカルのコンポーネントが勝ち、正しくハイドレートされます — が、ノイズになりますし、「片方を残し、片方を捨てる」という解決はスキャン順に依存します。パッケージから ThemeToggle をインポートすれば同じマーカーに登録されるため、衝突するものがなくなり、手書きコピーの保守負担からも解放されます。

並び順

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