## アイテムの並び順 カテゴリ内のページは`sidebar_position`フロントマターフィールドでソートされます。小さい値ほど先に表示されます。 `sidebar_position`がないページはデフォルト値`999`が適用され、カテゴリの末尾にファイル名のアルファベット順で表示されます。 ```mdx --- title: My Page sidebar_position: 3 --- ``` [Dynamic content unavailable in text export] ページの順序を制御するために、`sidebar_position`を常に明示的に設定してください。設定しないとページはアルファベット順にソートされ、意図した読み順と一致しない場合があります。 ## カテゴリの並び順 サイドバー内のカテゴリは**インデックスページ**（`index.mdx`）の`sidebar_position`で順序付けされます。カテゴリにインデックスページがない場合や`sidebar_position`がない場合は、アルファベット順にフォールバックします。 例えば、「Getting Started」を最初に、「Guides」を2番目にするには： ``` getting-started/index.mdx → sidebar_position: 0 guides/index.mdx → sidebar_position: 1 reference/index.mdx → sidebar_position: 2 ``` ## カテゴリインデックスページ ディレクトリ内に`index.mdx`を作成すると、カテゴリにランディングページが付与されます。サイドバーのカテゴリ名がこのページへのクリック可能なリンクになります。 一般的なカテゴリインデックスページでは``コンポーネントを使用して、カテゴリ内のすべてのページを自動的にリスト表示します： ```mdx --- title: Guides sidebar_position: 1 --- Explore our guides to learn about zudo-doc features. ``` ``コンポーネントは、カテゴリ内のすべてのページ（インデックス自体を除く）へのリンクのグリッドを`sidebar_position`でソートしてレンダリングします。 `index.mdx`がない場合、カテゴリの見出しはトグル専用のコントロールになります — クリックするとカテゴリの展開・折りたたみが行われますが、ページへのナビゲーションは行われません。 ## デフォルトの展開・折りたたみ 現在のページを含むカテゴリは常に展開されます。`sidebar_initial_expansion`を省略すると、通常のカテゴリは従来どおり展開されます。TypeScriptで明示した`collapsed`の値は個別の例外として維持されます。 カテゴリの`index.mdx`に`sidebar_initial_expansion: collapsed`または`expanded`を設定すると、その配下に初期状態を継承できます。最も近いカテゴリの設定が適用され、現在のページに設定した値がそれを上書きします。この設定は展開状態を制御し、`initialPath`は引き続きサイドバーの初期表示範囲を制御します。 ```mdx --- title: Guides sidebar_position: 1 sidebar_initial_expansion: collapsed --- ``` セッション内に保存されるのは、読者が明示的に行った展開・折りたたみの操作だけです。現在のページの祖先カテゴリを自動で開く動作（ページ到着時。戻る・進むやソフトナビゲーションを含み、画面幅を問いません）や、選択・拡大した表示範囲のルートを開く動作は保存されません。現在のページを含むカテゴリも折りたたむことができ、そのページでは折りたたまれたままになります。ハッシュの変更、フィルターへの入力、同じページの再読み込みでも再び開きません。別のページへ移動すると、そのページへの経路が再び開かれます。関係のない枝での選択は維持されます。 復元操作は現在のページの著者設定に展開状態と表示範囲を戻します。実際の状態がその基準と異なる場合にのみ復元ボタンが表示されます。最上位の表示範囲ではツールバー全体が非表示になり、各カテゴリの枝だけを表示する操作は引き続き利用できます。 [Dynamic content unavailable in text export] 以前のバージョンで保存された状態には、自動の展開と手動の展開が混在していました。そのため、アップグレード後の最初の読み込みで以前の展開・折りたたみ状態を一度だけ破棄します。保存された表示範囲とフィルターの文字列は維持されます。この処理は繰り返されません。 ## サイドバーラベル `sidebar_label`フロントマターフィールドを使用して、ページタイトルとは異なるラベルをサイドバーに表示できます。完全なタイトルがサイドバーには長すぎる場合に便利です。 ```mdx --- title: Getting Started with zudo-doc Installation sidebar_label: Installation sidebar_position: 2 --- ``` [Dynamic content unavailable in text export] `sidebar_label`はサイドバーにのみ影響します。ページタイトルと見出しには引き続き`title`が使用されます。 ## ディレクトリ構造 `src/content/docs/`内のディレクトリがサイドバーカテゴリになります。ディレクトリ名はkebab-caseからTitle Caseに自動的に変換されます。 ``` src/content/docs/ getting-started/ → "Getting Started" index.mdx → category index (sidebar_position: 0) introduction.mdx → sidebar_position: 1 installation.mdx → sidebar_position: 2 writing-docs.mdx → sidebar_position: 3 guides/ → "Guides" index.mdx → category index (sidebar_position: 1) configuration.mdx → sidebar_position: 1 frontmatter.mdx → sidebar_position: 2 ``` ## ネストカテゴリ（サブグループ） カテゴリディレクトリ内にサブディレクトリを作成すると、サイドバーにネストされた折りたたみグループが生成されます。各サブディレクトリには `category_no_page: true` を含む `index.mdx` ファイルが必要です： ``` src/content/docs/ methodology/ index.mdx architecture/ index.mdx → title: Architecture, sidebar_position: 1, category_no_page: true bem-strategy.mdx component-first.mdx design-systems/ index.mdx → title: Design Systems, sidebar_position: 2, category_no_page: true tight-token.mdx two-tier-size.mdx ``` 自動生成サイドバーでは **3レベルの深さ** で表示されます： ``` Methodology (depth 0) ▸ Architecture (depth 1, collapsible) BEM Strategy (depth 2) Component First (depth 2) ▸ Design Systems (depth 1, collapsible) Tight Token (depth 2) Two-Tier Size (depth 2) ``` ### 明示的サイドバー設定によるフラット化 より読みやすくするため、明示的なサイドバー設定を使用してサブグループをトップレベルに昇格できます。ネストが1レベル減少します。設定ファイルは自動で消費されないため、`sidebarsConfig` chrome スロットからバインドしてください。 [Dynamic content unavailable in text export] `sidebarsConfig` のデフォルトは `{}` で、すべてのセクションがファイルシステムの自動生成を使います。`chromeBindingsModule` を設定をバインドするモジュールへ向けてください。新しいルートスタブはそれをすでに消費するため編集しません。詳しくは [Custom Components](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components) と [ホストクロームバインディング](https://zudo-doc.takazudomodular.com/ja/docs/reference/host-chrome-bindings)を参照してください。 `headerNav`内の`categoryMatch`値と正確に一致するキーを持つ設定を作成し、バインドします。 ```ts title="src/sidebars.ts" import type { SidebarsConfig } from "@takazudo/zudo-doc/sidebar-utils"; const sidebars: SidebarsConfig = { guides: [ "guides/introduction", { type: "doc", id: "guides/sidebar", label: "Sidebar" }, { type: "link", label: "Project site", href: "https://example.com" }, { type: "category", label: "Architecture", collapsed: true, sortOrder: "asc", items: [{ type: "autogenerated", dirName: "guides/architecture" }], }, ], }; export default sidebars; ``` 文字列形式はドキュメント id の省略形です。利用できるアイテムの完全な語彙は、文字列の `"doc/slug"`、`{ type: "doc", id, label? }`、`{ type: "link", label, href }`、 `{ type: "category", label, items, collapsed?, sortOrder? }`、 `{ type: "autogenerated", dirName? }`です。一致するキーがないセクションは、 ファイルシステムの自動生成にフォールバックします。 ```ts title="src/chrome-bindings.ts" import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings"; import sidebars from "./sidebars"; export const chromeBindings = defineChromeBindings({ sidebarsConfig: sidebars, }); ``` ```ts title="zfb.config.ts" export default defineConfig( zudoDoc({ chromeBindingsModule: "./src/chrome-bindings.ts", }), ); ``` このリポジトリの`src/config/sidebars.ts`はショーケース専用の参照ファイルです。現在は 空のオブジェクトをエクスポートしているため、このショーケースではすべてのセクションに ファイルシステムの自動生成を意図的に使っています。 ```ts title="src/sidebars.ts" const sidebars: SidebarsConfig = { methodology: [ "methodology", { type: "category", label: "Architecture", items: [{ type: "autogenerated", dirName: "methodology/architecture" }], }, { type: "category", label: "Design Systems", items: [{ type: "autogenerated", dirName: "methodology/design-systems" }], }, ], }; ``` **2レベル** で表示されます： ``` Methodology (depth 0, leaf link) ▸ Architecture (depth 0, collapsible) BEM Strategy (depth 1) Component First (depth 1) ▸ Design Systems (depth 0, collapsible) Tight Token (depth 1) Two-Tier Size (depth 1) ``` ポイント： - 文字列 `"methodology"` はカテゴリインデックスページを **リーフリンク** として参照します（子要素は自動的に除去され、明示的な設定が構造を制御します） - `type: "autogenerated"` と `dirName` で特定のサブディレクトリから記事を取得します - サブグループカテゴリは depth 0 で太字ラベルとボーダー区切り付きで表示されます - 記事は depth 1 で表示され、自動生成より1レベルフラットになります [Dynamic content unavailable in text export] カテゴリにサブグループがある場合はこのパターンを推奨します。明示的な設定によりファイルシステムの整理を維持しつつ、サイドバーの可読性が向上します。 ## ソート順（昇順・降順） デフォルトでは、カテゴリ内のアイテムは昇順（`sidebar_position`が小さい順、次にアルファベット順）でソートされます。カテゴリの `index.mdx` の `category_sort_order` フロントマターフィールドを使用してカテゴリごとに降順に変更できます： ```mdx title="changelog/index.mdx" --- title: Changelog sidebar_position: 10 category_sort_order: "desc" --- ``` `category_sort_order`が`"desc"`の場合、アイテムは逆順でソートされます — positionが大きい順、次に逆アルファベット順。これは日付ベースのコンテンツ（変更履歴、リリースノート）で、最新のアイテムを上部に表示したい場合に便利です。 ノートトレイでは、同じフィールドがすべての並び順を決めます。指定した向きは、サイドバー、``、前・次ページャー、ホームページのブロックで安定したrankを並べる向きを制御しますが、rankの値自体は変わりません。`note_tray_sidebar: "year"`または`"month"`ではグループもその向きの時系列で並び、グループ内のアイテムはrank順になります。日付グループと読み順が一致するよう、`sidebar_position`は`date`と同じ時系列で付けてください。詳しい設定は[ノートトレイ](https://zudo-doc.takazudomodular.com/ja/docs/guides/note-tray)を参照してください。 [Dynamic content unavailable in text export] `_category_.json` は引き続き動作しますが、zfb のビルド警告が発生します。新しいカテゴリには `index.mdx` のフロントマターを使用してください。 バインドしたサイドバー設定では、手動サイドバー設定に`sortOrder`を設定することもできます： ```ts { type: "category", label: "Releases", sortOrder: "desc", items: [ { type: "autogenerated" }, ], } ``` [Dynamic content unavailable in text export] 変更履歴スタイルのカテゴリでは、`sortOrder: "desc"`と日付プレフィックスのファイル名（例：`2026-03-10-release.mdx`）を組み合わせることで、`sidebar_position`を手動設定しなくても自動的に最新順に並べられます。 ## 並び順の推奨事項 - 予測可能な順序のためにすべてのページに`sidebar_position`を設定する - カテゴリインデックスページには`sidebar_position: 0`を使用する - 各カテゴリ内のページには連番（1, 2, 3...）を使用する - 後でページを挿入する予定がある場合は番号に間隔を空ける（例：10, 20, 30） - 最新順のカテゴリには`index.mdx`で`category_sort_order: "desc"`を使用する - ノートトレイでは`note_tray_sidebar: "index"`、`"year"`、`"month"`から選択する。yearとmonthでは全アイテムに日付が必要 ## ツリーを広げる フィルターの下のコントロールは、記事、読書位置、目次を変えずに表示するナビゲーションを切り替えます。**ツリーを広げる**は編集上の親へ一段ずつ移動します。表示できる最上位では範囲ツールバー（ツリーを広げる・現在のページのツリーに戻す）全体が非表示になり、無効化されたボタンやヒントは表示されません。カスタム設定の複数ルートが最上位になる場合もあります。 各カテゴリーには独立した**この枝だけを表示**ボタンがあります。カテゴリーのリンクはページを開き、開閉ボタンは子項目を開閉します。別の範囲を表示している間は**現在のページのツリーに戻す**が表示され、現在のページに設定されたルートと順序を復元します。モバイルのドロワーでも範囲操作では閉じず、ページリンクでは通常どおり閉じます。 範囲を変えてもフィルターは保持されます。カテゴリーが一致すれば子孫を保持し、子孫が一致すればその祖先を保持します。枝の開閉状態は広げる操作と枝の選択で保持されます。復元操作は設定された基準（`initialPathMode: "node"` を含む）に戻し、選択中の範囲と保存された展開・折りたたみの選択を消去し、フィルターの文字列は維持したまま現在のページへの経路を開きます。フィルターがそのページを除外している場合は解除してください。デスクトップのサイドバーとモバイルのドロワーは同時に更新されます。ツリーは再帰的で、深さの制限はありません。 範囲はセッション内の一時状態です。`initialPath` と `initialPathMode` が決めるのは、初回表示と復元時の基準だけです。編集コンテキスト（同じ完全な `items` ツリーに同じ `contextId` を指定したもの、または自動生成ツリー）を共有するセクションは保存状態も共有するため、読者が選んだ拡大・選択の範囲は復元するまでそれらのページで維持されます。選択範囲内のリンクでは範囲を保持し、別の枝への移動では最も近い共通の親まで広げます。言語、バージョン、独立したドキュメントのコンテキストを変えると移動先の設定に戻ります。構造変更後の古い範囲は無効になります。保存された範囲の表示が現在のページの基準と同じ場合は基準として扱われ、復元ボタンは表示されません。URLや修飾キー付きクリック、新しいタブの動作は従来どおりです。 ### 編集上の親を明示する 既存の配列設定は初期表示を維持します。ローカルな表示範囲の外側に親を指定するにはオブジェクト形式を使います。`items` は編集上のツリー全体を定義し、`initialPath` は解決・並び替え後のツリーにおけるゼロ始まりのインデックスで、初期表示する子項目の親を指定します。次の例では初期表示が Background と Border、その上が Surfaces & borders、さらに上が Utility reference です。これらのグループはURLに含まれている必要がありません。 ```ts title="src/sidebars.ts" import type { SidebarsConfig } from "@takazudo/zudo-doc/sidebar-utils"; const sidebars: SidebarsConfig = { utilities: { contextId: "utility-reference", items: [ { type: "category", label: "Utility reference", items: [ { type: "category", label: "Surfaces & borders", items: ["utilities/background", "utilities/border"], }, ], }, ], initialPath: [0, 0], }, }; export default sidebars; ``` 上の設定例と同様に `chromeBindings.sidebarsConfig` へ渡します。`contextId` は省略可能です。同じ完全な `items` ツリーを共有し、異なる `initialPath` を使うセクションには同じ値を指定します。言語、バージョン、構造のリビジョンは自動的に追加されます。不正なパスでは親を推測せず、ビルドが失敗します。 #### ノード自体を選択する `initialPathMode` は `initialPath` が何を選ぶかを決めます。既定値の `"children"` では、選択したカテゴリの子項目を表示します。`"node"` では、選択したノード自体が基準になり、その行（ページを持つセクションは概要ページへのリンクを維持）と子項目を表示します。`navigation.roots` には引き続き編集上のツリー全体が含まれるため、ツリーを広げると対象の実際の親へ、さらにその上へと移動します。親の行が重複したり、存在しない親が作られたりすることはありません。 ```ts title="src/sidebars.ts" import type { SidebarsConfig } from "@takazudo/zudo-doc/sidebar-utils"; const sidebars: SidebarsConfig = { wind: { items: [{ type: "autogenerated", dirName: "wind" }], // Utility reference → Surfaces & borders initialPath: [0, 0], initialPathMode: "node", }, }; export default sidebars; ``` 自動生成されたツリー Wind → Utility reference → Surfaces & borders → Background color で、`initialPath` が Surfaces & borders を指す場合を考えます。Background color のページでは、node モードは最初に Surfaces & borders（概要ページへのリンク付き）とその配下のページを表示し、ツリーを広げると Utility reference、続いて Wind を表示します。children モードでは最初に Surfaces & borders 配下のページだけを表示し、最初にツリーを広げると Surfaces & borders の行が加わります。 `initialPath` がない、または空の場合は、どちらのモードでも解決済みのツリー全体を表示します。node モードでは、葉のページで終わる有効なパスも指定でき、そのページだけを表示します。不正なインデックスや、それ以外の `initialPathMode` の値はビルドを失敗させます。どちらのモードもデスクトップのサイドバーとモバイルのドロワーで同じように動作します。 `items` が空のオブジェクト形式（`items: []`）では、エントリを省略した場合と同じくカテゴリで絞り込んだ自動生成ツリーを使い、そこに `initialPath` と `initialPathMode` を適用します。`buildSidebarForSection` と `buildSidebarNavigation` は同じ結果になり、不正なパスやモードも同様に失敗します。エントリの省略や空の配列は、従来どおり自動生成ツリーのみを使います。 `autogenerated` は表示から省いたディレクトリルートの由来を保持します。手書きのグループ構造が優先され、同じラベルや同じページへの複数リンクも別々の項目として識別されます。共通の親を持たないカスタムの複数ルートでは、そこで広がりが止まります。ヘッダーのドロップダウングループはドキュメントの祖先にはなりません。 独自の統合では `@takazudo/zudo-doc/sidebar-utils` の `buildSidebarNavigation` を呼び、返された `nodes` と `navigation` を `SidebarTree` または `SidebarToggle` に渡せます。`buildSidebarForSection` と `nodes` だけを渡す形式も引き続き利用でき、後者では範囲コントロールを追加せず従来のツリーを表示します。 ### クライアントへ渡すナビゲーションデータ 標準のヘッダーとサイドバーファクトリーは、サイドバーアイランドが必要とするフィールドだけをコピーします。ページの説明文はカテゴリ表示用のサーバーナビゲーションデータに残りますが、ブラウザーへ送る表示中のノードと広い範囲のツリーからは再帰的に除かれます。モバイルの `sidebarNodes` 配列とコールバックの戻り値は、URL を書き換えずにコピーされます。オブジェクトの同一性は保持しません。 独自のホストでは、`SidebarTree` または `SidebarToggle` のアイランドを作る前に `@takazudo/zudo-doc/sidebar` の `toSidebarClientData(nodes, navigation)` を呼び、戻り値を SSR とハイドレーションの両方に渡せます。このヘルパーはフィールドを選ぶ前に入力を検証し、項目の識別子、ツリー構造、展開の初期値、既存のナビゲーションコンテキスト ID を維持します。説明文の変更は引き続きコンテキスト ID に影響する場合があります。これは転送データの削減であり、プライバシー境界や表示範囲の保存方式を変更するものではありません。