フロントマタープレビュー

カスタムフロントマターフィールドをページタイトルの下にメタデータテーブルとして表示するよう設定します。

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

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

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

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,
});

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

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

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

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

デフォルト無視リスト

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

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

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

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

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

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

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

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

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

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

機能を無効にする

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

frontmatterPreview: false,

使用例

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

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

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

完全な設定リファレンスについては、設定 — frontmatterPreview を参照してください。

カスタムレンダラー

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

コンポーネントの型

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

レンダラーの登録

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

discount: ({ value }) => {
  if (value !== true) return null;
  return (
    <span className="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 の無視リストからそのキーを削除してください：

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

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