ノートトレイ
ノートや日誌など、順番に読む文章のためのフラットなカテゴリを作成します。
ノートトレイは、フラットなページ列をまとめるトップレベルカテゴリです。トレイに重ねた紙をイメージしてください。日誌なら最新の1枚を一番上に置き、講座やノート集なら順番に読み進められます。並び順はsidebar_positionで決まり、日付はソートキーではなく任意のメタデータです。
ノートトレイを宣言する
必須のカテゴリindex.mdxでトレイを宣言します。
---
title: Notes
sidebar_position: 3
category_shape: "note-tray"
category_sort_order: "desc"
note_tray_dated: true
note_tray_sidebar: "month"
---
Recent notes, newest first.
<NoteTrayIndex style="timeline" />各アイテムはindexと同じディレクトリに直接置きます。
---
title: First Note
description: What changed and why.
sidebar_position: 1
date: "2026-08-20"
updated: "2026-08-22"
---
## Summary
Note content begins here.ここではdate: 2026-08-22とdate: "2026-08-22"は同じ扱いです。zfbは引用符の有無にかかわらずフロントマターのスカラー値を文字列として保持し、スキーマがYYYY-MM-DD形式を検証したうえで、ビルドが暦上存在しない日付を拒否します。これらのフィールドを利用する別のYAML 1.1ツール（js-yamlなど）が、引用符のない日付をDateオブジェクトに変換する場合に限り、相互運用性のために引用符を付けてください。
宣言キー
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
category_shape | "note-tray" | 未指定（通常のツリーカテゴリ） | このトップレベルカテゴリをノートトレイとして宣言 |
note_tray_dated | boolean | false | unlistedのアイテムを含む全アイテムにdateを必須化 |
note_tray_sidebar | "index" | "year" | "month" | "index" | トレイのサイドバー表示を選択。yearとmonthには日付付きトレイが必要 |
category_sort_order | "asc" | "desc" | "asc" | サイドバー・インデックス・ページャー・ホームページすべての順序を指定 |
date | "YYYY-MM-DD" | — | アイテムの日付。日付付きトレイでは必須、その他のドキュメントでは任意 |
updated | "YYYY-MM-DD" | — | どのドキュメントにも指定できる任意の更新日 |
並び順のキーは引き続きsidebar_positionです。zudo-docは、まずposition、次にslugの昇順で並べた結果から、1始まりの安定したrankを導出します。rankはアイテム数に応じた桁数でゼロ埋めされ、表示順を降順にしても変わりません。そのため、6件の降順トレイは06から01と表示されます。positionの未指定・小数・重複は通常のカテゴリと同じように扱われ、ノートトレイ独自のposition検証はありません。
日付付きトレイでは、sidebar_positionがdateと同じ時系列になるように付けることを推奨します。これは検証ルールではありませんが、日付グループ内の読み順が不自然になるのを防げます。
サイドバーのスタイル
トレイのindexにnote_tray_sidebarを設定します。
| スタイル | 適した場面 |
|---|---|
"index" | 読む順番を最も重視するとき。ゼロ埋めしたrankを表示し、日付の有無を問わず利用可能 |
"year" | 長期間にわたる日付付きアーカイブを年単位で探したいとき |
"month" | 更新頻度の高い日誌を月単位で細かくまとめたいとき |
年・月グループはcategory_sort_orderに従って時系列で並び、グループ内のアイテムも同じ向きのrank順になります。グループ化したサイドバーでは各アイテムにMM-DDを表示し、通常のindexサイドバーではrankを表示します。サイドバーにdateは表示されますが、updatedは表示されません。
NoteTrayIndex
NoteTrayIndexはMDXでグローバルに利用できます。トレイのindexでは現在のトレイを自動判定し、別のページから使う場合はcategoryを明示できます。
<NoteTrayIndex />
<NoteTrayIndex style="cards" showDate />
<NoteTrayIndex category="notes" style="timeline" />3つのスタイルがあります。
index（デフォルト）— タイトルとdescriptionを並べるコンパクトな番号付きリスト。行全体がリンクcards— descriptionとタグを含む、アイテムごとのカード。カード全体がリンクで、タグはそれぞれ独立したリンクtimeline— 月ごとにまとめたタイムライン。レール上には日を示す数字を置き、各アイテムはタイトルから始まる。note_tray_dated: trueが必要
indexとcardsでは、showDateを設定しない限り日付を表示しません。この2つのスタイルでは、updatedをローカライズされた「更新」ラベルとともにdateの隣に表示します。timelineでは作成日だけを常に表示し、updatedは表示しません。updatedだけのアイテムでは、showDateを設定したindexとcardsに限り、その値だけを表示します。空のトレイは何もレンダリングしません。
実例はNoteTrayIndexコンポーネントページを参照してください。
ホームページとページャー
ホームページはノートトレイを自動的に認識します。ネストしたカテゴリツリーとしてではなく、同じフラットなトレイ順とサイドバーのグループ設定を使って表示します。日付付きブロックには作成日を示すdateだけを表示し、日付なしのブロックにはrankを表示します。空のトレイは表示されません。
前・次リンクもトレイのrank順とcategory_sort_orderに従います。dateがあれば表示しますが、updatedは表示しません。
検証エラー
pnpm buildはロケールとバージョンごとに検証し、Invalid note-tray configurationの下に問題のあるslugをすべて表示します。次のように修正してください。
| エラー | 修正方法 |
|---|---|
category_shape is only allowed on top-level categories | トレイのディレクトリをdocsコンテンツルート直下へ移動 |
a note tray must be declared by a category index.mdx | トレイディレクトリのindex.mdxへ宣言を移動 |
note-tray children must be flat leaf files | ネストしたページをトレイ直下へ移し、子ディレクトリを削除 |
dated note-tray children require date | unlistedを含む全アイテムに、暦上有効なdate（YYYY-MM-DD）を追加 |
year grouping requires note_tray_dated: trueまたはmonth grouping requires note_tray_dated: true | note_tray_datedを有効にするか、note_tray_sidebar: "index"を使用 |
a note-tray index must be a visible routed page | indexからcategory_no_page: true、unlisted: true、standalone: trueを外し、ルートが生成されるようにする |
date is not a calendar-valid YYYY-MM-DD valueまたは同等のupdatedエラー | "2026-02-28"のような実在する日付を使用。"2026-02-31"などは不可 |
コンテンツスキーマは、まずYYYY-MM-DD形式に一致しない文字列を拒否します。その後、ノートトレイの検証で暦上存在しない日付を拒否します。
制限事項
ノートトレイは意図的に用途を絞った機能です。
トップレベルカテゴリでのみ使用できます。
アイテムはフラットなファイルだけです。ネストしたトレイやサブディレクトリには対応しません。
トレイには、表示されルートを持つ
index.mdxが必要です。通常のdocsコレクションとルートを使い、サイドバーなしの記事レイアウトを新たに追加するものではありません。
並び順は
sidebar_positionとcategory_sort_orderだけで決まり、実行時のソート切り替えはありません。ページ分割、RSS、抜粋、著者、読了時間、「最新N件」のサイドバーは組み込まれていません。
トレイは通常のヘッダーナビ項目として扱われ、専用バッジやドロップダウンはありません。
ショーケースの変更履歴を含む既存カテゴリが、自動的にノートトレイへ変換されることはありません。