ヘッダーの右側 — 検索、外観メニュー、言語スイッチャー、バージョンスイッチャー、GitHub リンク、Design Token / AI Chat トリガー — は `headerRightItems` という 1 つの配列フィールドからレンダリングされます。各エントリは discriminated union で、配列の順番どおりに描画されます。
[Dynamic content unavailable in text export]
左側のタブは [ヘッダーナビゲーション](https://zudo-doc.takazudomodular.com/ja/docs/guides/header-navigation) で設定します。どちらも `zfb.config.ts` に定義しますが、互いに独立しています。
## デフォルト設定
```ts title="zfb.config.ts"
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` にはフラグによる制御がありません。
| コンポーネント | 機能フラグ |
|---|---|
| `theme-toggle` | `colorMode` |
| `language-switcher` | `locales`(少なくとも 1 つの非デフォルトロケールが必要) |
| `version-switcher` | `versions` |
| `github-link` | `githubUrl` |
| `search` | なし — 常に利用可能 |
```ts
{ type: "component", component: "github-link" }
```
機能を無効化すればエントリは黙って除外されるので、配列に残したままでも問題ありません。`search` には専用の機能フラグがありません — レンダラーは常に利用可能で、表示するかどうか・どの位置に表示するかは配列内の記述だけで決まります。
### `trigger`
組み込みのモーダルやパネルを開きます。
| トリガー | 機能フラグ |
|---|---|
| `design-token-panel` | `designTokenPanel` |
| `ai-chat` | `aiAssistant` |
```ts
{ type: "trigger", trigger: "ai-chat" }
```
`design-token-panel` トリガーボタンは `window` に `toggle-design-token-panel` カスタムイベントをディスパッチします。zdtpパネル（`@takazudo/zdtp`）はこのイベントをネイティブに受け取るため、追加の配線は不要です。
### `link`
任意の外部/内部リンクをアイコン付きで描画します。
```ts
{
type: "link",
href: "https://discord.example",
ariaLabel: "Discord",
icon: "github", // only "github" is bundled today
}
```
外部 URL は自動的に新しいタブで開きます。
### `html`
任意のマークアップを差し込むためのエスケープハッチです。
```ts
{ type: "html", html: 'beta' }
```
文字列がそのまま出力されるため、使いどころは限定してください。
## カスタマイズ例
### GitHub アイコンをあなたのリポジトリへ向ける
`zfb.config.ts`の`zudoDoc({...})`でトップレベルの `githubUrl` を書き換えるだけで済みます。`github-link` コンポーネントはこの値を読むので、配列側に URL を書き足す必要はありません。
```ts title="zfb.config.ts"
export default defineConfig(
zudoDoc({
githubUrl: "https://github.com/your-org/your-repo",
}),
);
```
`githubUrl: false` を指定すると、配列を編集せずにアイコンだけ消せます。
### アイテムを外す
機能フラグでの非表示ではなく、配列から該当エントリを削除してください。たとえば AI chat トリガーを隠すなら:
```ts
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" },
],
```
### カスタムリンクを追加する
```ts
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](https://zudo-doc.takazudomodular.com/ja/docs/reference/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`をインポートし、固定ターゲットのサーバー境界で合成します。
```tsx
import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
```
エクスポートされる `ThemeToggle` は、コンパクトな `