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

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

フロントマタープレビューブロックは、ドキュメントに無視されていないフロントマターキーが含まれている場合、ページタイトルの下に自動的に表示されます。カスタムフィールドをコンパクトなキー/値テーブルとしてレンダリングし、著者情報、ステータス、バージョンなどのドキュメントメタデータを本文中に埋め込まずに表示するのに便利です。

このページ自体がその機能のデモです。上部に表示されている author と status フィールドは、このページ自身のフロントマターで宣言されています。

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

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

src/config/settings.ts で frontmatterPreview: false を設定すると、すべてのページでこの機能を無効にできます。

デフォルト無視リスト

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

このリストにないキーは自動的に表示されます。

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

src/config/settings.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 を参照してください。

カスタムレンダラー

デフォルトでは、フロントマターの値はプレーンテキストとしてレンダリングされます。値をスタイル付きコンポーネント（カラーピル、リンク、アイコンなど）に置き換えるには、src/config/frontmatter-preview-renderers.tsx にカスタムレンダラーを登録します。

コンポーネントの型

各レンダラーは FrontmatterRendererProps を受け取る Preact コンポーネントです：

レンダラーの登録

src/config/frontmatter-preview-renderers.tsx を開き、エクスポートされた frontmatterRenderers マップにキーを追加します。各値は FrontmatterRendererProps を受け取り、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 など）をカスタムレンダラーで表示するには、まず src/config/settings.ts の無視リストからそのキーを削除してください：

frontmatterPreview: {
  // 非表示にするすべてのキーを明示的に列挙 — ignoreKeys はデフォルトを置き換えます
  ignoreKeys: ["title", "description", "sidebar_position", "tags"],
},

レンダラーはプロジェクトの src/config/frontmatter-preview-renderers.tsx に登録します。デフォルトでは空のマップが用意されています。