フロントマタープレビューブロックは、カスタムフロントマターフィールドをページタイトルの下にコンパクトなキー/値テーブルとしてレンダリングします。著者情報、ステータス、バージョンなどのドキュメントメタデータを本文中に埋め込まずに表示するのに便利です。新しいscaffoldでは自動的には有効になりません。`frontmatterPreview`のデフォルトは`false`であり、バインドされていない`buildFrontmatterPreviewEntries`スロットのデフォルトは`() => []`です。

このショーケースページがその機能のデモです。上部に表示されている`author`と`status`フィールドは、このページ自身のフロントマターで宣言され、ショーケースの bindings がエントリービルダーを提供しています。

[Dynamic content unavailable in text export]

`buildFrontmatterPreviewEntries` のデフォルトは no-op です。`chromeBindingsModule` をそのスロットをバインドするモジュールへ向けてください。新しいルートスタブはそのモジュールをすでに消費するため編集しません。詳しくは [Custom Components](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components) と [ホストクロームバインディング](https://zudo-doc.takazudomodular.com/ja/docs/reference/host-chrome-bindings)を参照してください。



設定を有効にし、bindingsモジュールにビルダーを作成します。ビルダーの`frontmatterPreview`へ渡す値は、
`zudoDoc()`の設定と一致させてください。

```ts title="src/chrome-bindings.ts"
import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
import { createBuildFrontmatterPreviewEntries } from "@takazudo/zudo-doc/frontmatter-preview-data";
import { defaultFrontmatterPreviewIgnoreKeys } from "@takazudo/zudo-doc/frontmatter-preview-defaults";
import { frontmatterRenderers } from "./frontmatter-preview-renderers";

export const chromeBindings = defineChromeBindings({
  buildFrontmatterPreviewEntries: createBuildFrontmatterPreviewEntries({
    frontmatterPreview: {},
    defaultIgnoreKeys: defaultFrontmatterPreviewIgnoreKeys,
  }),
  frontmatterRenderers,
});
```

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    frontmatterPreview: {},
    chromeBindingsModule: "./src/chrome-bindings.ts",
  }),
);
```

## ブロックが表示される条件

有効化してバインドした後、フィルタリングを経て少なくとも1つのフロントマターキーが残った場合のみブロックが表示されます。フレームワーク管理のキー（`title`、`description`、`sidebar_position`、`tags` など）はデフォルトで除外されます。すべてのキーが無視リストに含まれている場合は何も表示されません。

`zfb.config.ts`（`zudoDoc({...})` の呼び出し）で `frontmatterPreview: false` を設定すると、すべてのページでこの機能を無効にできます。

## デフォルト無視リスト

以下のキーはデフォルトで無視されます。これらはコンテンツスキームで定義されたすべてのフィールドに対応しており、再表示しても冗長になるだけです。

| キー | 理由 |
|-----|------|
| `title` | ページの `h1` としてレンダリング |
| `description` | タイトルの下にサブタイトルとして表示 |
| `sidebar_position` | ナビゲーション内部メタデータ |
| `sidebar_label` | ナビゲーション内部メタデータ |
| `category` | ナビゲーション内部メタデータ |
| `tags` | タグバッジとして別途レンダリング |
| `search_exclude` | ビルド時フラグ |
| `pagination_next` | ビルド時フラグ |
| `pagination_prev` | ビルド時フラグ |
| `draft` | ビルド時フラグ |
| `unlisted` | ビルド時フラグ |
| `hide_sidebar` | レイアウトフラグ |
| `hide_toc` | レイアウトフラグ |
| `standalone` | レイアウトフラグ |
| `slug` | URL オーバーライド |
| `generated` | ビルド時フラグ |

ビルダーをバインドすると、このリストにないキーは自動的に表示されます。

## 無視リストのカスタマイズ

`zudoDoc({...})`（`zfb.config.ts` に設定）の `frontmatterPreview` フィールドには、互いに排他的な2つの設定があります。

### `extraIgnoreKeys` — デフォルトを拡張する

デフォルト設定を破棄せずにキーを無視リストに追加します。プロジェクト全体で非表示にしたいカスタムフロントマターフィールドがある場合に使用します。

```ts
frontmatterPreview: {
  extraIgnoreKeys: ["reviewed_by", "internal_id"],
},
```

### `ignoreKeys` — デフォルトを置き換える

組み込みの無視リストを完全に置き換えます。非表示にするキーを完全に制御したい場合に使用します。`ignoreKeys` が存在する場合、`extraIgnoreKeys` は無視されます。

```ts
frontmatterPreview: {
  ignoreKeys: ["title", "description", "sidebar_position"],
},
```

[Dynamic content unavailable in text export]

`ignoreKeys` を使用する際に標準スキーマキーを含めないと、`draft` や `unlisted` などのフレームワーク内部フィールドがテーブルに表示される可能性があります。ほとんどの場合、`extraIgnoreKeys` を使用する方が安全です。



## 機能を無効にする

`frontmatterPreview: false` を設定すると、すべてのページからブロックを一括削除できます。

```ts
frontmatterPreview: false,
```

## 使用例

次のフロントマターは `author` と `status` が表示されるプレビューテーブルを生成します。`title`、`description`、`sidebar_position` はフィルタリングされます。

```mdx
---
title: My Release Notes
description: What changed in v2.
sidebar_position: 5
author: Jane Doe
status: released
---
```

レンダリングされたテーブル：

| キー | 値 |
|-----|---|
| `author` | Jane Doe |
| `status` | released |

完全な設定リファレンスについては、[設定 — frontmatterPreview](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E3%82%B5%E3%82%A4%E3%83%88%E8%A8%AD%E5%AE%9A-frontmatterpreview) を参照してください。

## カスタムレンダラー

デフォルトでは、フロントマターの値はプレーンテキストとしてレンダリングされます。値をスタイル付きコンポーネント（カラーピル、リンク、アイコンなど）に置き換えるには、独自のレンダラーマップを作成し、上記の`frontmatterRenderers`スロットからバインドします。このリポジトリの`src/config/frontmatter-preview-renderers.tsx`は`src/chrome-bindings.tsx`を通すショーケース配線の例です。新しいscaffoldにはどちらのファイルもありません。

### コンポーネントの型

各レンダラーは `@takazudo/zudo-doc/metainfo` の `FrontmatterCellRendererProps` を受け取る zudo-react コンポーネントです：

| プロップ | 型 | 説明 |
|------|------|-------------|
| `value` | `NonNullable<unknown>` | フロントマターの値（null/undefined は渡されません） |
| `entryKey` | `string` | フロントマターのキー名 |
| `data` | `Record<string, unknown>` | 現在のページのフロントマター全体 |
| `locale` | `string \| undefined` | アクティブなロケール |

### レンダラーの登録

独自のレンダラーマップにキーを追加します。各値は`FrontmatterCellRendererProps`を受け取り、JSXまたは`null`を返すコンポーネント関数です：

```tsx
discount: ({ value }) => {
  if (value !== true) return null;
  return (
    <span class="inline-block px-hsp-sm py-vsp-2xs text-caption rounded-full bg-danger text-fg">
      ON SALE
    </span>
  );
},
```

このページのフロントマターには `discount: true`、`status: "stable"`、`difficulty: "beginner"` が含まれており、ページ上部のメタデータテーブルにカラーピルとして表示されています。

### 無視リストの優先順位

無視リストに登録されているキーのレンダラーは効果がありません。無視リストはレンダラーの検索より _前_ に適用されます。キーが抑制されている場合、行はレンダリングされず、レンダラーも呼び出されません。

フレームワーク管理のキー（`draft` など）をカスタムレンダラーで表示するには、まず `zfb.config.ts` に設定した `frontmatterPreview` の無視リストからそのキーを削除してください：

```ts
frontmatterPreview: {
  // Must explicitly list all keys to keep hidden — ignoreKeys replaces the defaults
  ignoreKeys: ["title", "description", "sidebar_position", "tags"],
},
```

[Dynamic content unavailable in text export]

`ignoreKeys` はデフォルトの無視リスト全体を置き換えます。`tags`、`slug`、`unlisted` などの標準スキーマキーを省略すると、それらがプレビューテーブルに表示されます。ほとんどの場合、デフォルトを拡張する `extraIgnoreKeys` の使用を推奨します。



ショーケースのレンダラーマップはscaffoldされず、自動で消費されるものでもありません。独自のマップを`frontmatterRenderers`からバインドしてください。このスロットを省略すると、すべての値はプレーンテキストのフォールバックのままです。