サイドバー

サイドバーナビゲーションの構造と設定方法。

アイテムの並び順

カテゴリ内のページはsidebar_positionフロントマターフィールドでソートされます。小さい値ほど先に表示されます。

sidebar_positionがないページはデフォルト値999が適用され、カテゴリの末尾にファイル名のアルファベット順で表示されます。

---
title: My Page
sidebar_position: 3
---

カテゴリの並び順

サイドバー内のカテゴリはインデックスページ（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を作成すると、カテゴリにランディングページが付与されます。サイドバーのカテゴリ名がこのページへのクリック可能なリンクになります。

一般的なカテゴリインデックスページでは<CategoryNav />コンポーネントを使用して、カテゴリ内のすべてのページを自動的にリスト表示します：

---
title: Guides
sidebar_position: 1
---

Explore our guides to learn about zudo-doc features.

<CategoryNav category="guides" />

<CategoryNav />コンポーネントは、カテゴリ内のすべてのページ（インデックス自体を除く）へのリンクのグリッドをsidebar_positionでソートしてレンダリングします。

index.mdxがない場合、カテゴリの見出しはトグル専用のコントロールになります — クリックするとカテゴリの展開・折りたたみが行われますが、ページへのナビゲーションは行われません。

デフォルトの展開・折りたたみ

現在のページを含むカテゴリは常に展開されます。sidebar_initial_expansionを省略すると、通常のカテゴリは従来どおり展開されます。TypeScriptで明示したcollapsedの値は個別の例外として維持されます。

カテゴリのindex.mdxにsidebar_initial_expansion: collapsedまたはexpandedを設定すると、その配下に初期状態を継承できます。最も近いカテゴリの設定が適用され、現在のページに設定した値がそれを上書きします。この設定は展開状態を制御し、initialPathは引き続きサイドバーの初期表示範囲を制御します。

---
title: Guides
sidebar_position: 1
sidebar_initial_expansion: collapsed
---

セッション内に保存されるのは、読者が明示的に行った展開・折りたたみの操作だけです。現在のページの祖先カテゴリを自動で開く動作（ページ到着時。戻る・進むやソフトナビゲーションを含み、画面幅を問いません）や、選択・拡大した表示範囲のルートを開く動作は保存されません。現在のページを含むカテゴリも折りたたむことができ、そのページでは折りたたまれたままになります。ハッシュの変更、フィルターへの入力、同じページの再読み込みでも再び開きません。別のページへ移動すると、そのページへの経路が再び開かれます。関係のない枝での選択は維持されます。

復元操作は現在のページの著者設定に展開状態と表示範囲を戻します。実際の状態がその基準と異なる場合にのみ復元ボタンが表示されます。最上位の表示範囲ではツールバー全体が非表示になり、各カテゴリの枝だけを表示する操作は引き続き利用できます。

サイドバーラベル

sidebar_labelフロントマターフィールドを使用して、ページタイトルとは異なるラベルをサイドバーに表示できます。完全なタイトルがサイドバーには長すぎる場合に便利です。

---
title: Getting Started with zudo-doc Installation
sidebar_label: Installation
sidebar_position: 2
---

ディレクトリ構造

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 スロットからバインドしてください。

headerNav内のcategoryMatch値と正確に一致するキーを持つ設定を作成し、バインドします。

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? }です。一致するキーがないセクションは、 ファイルシステムの自動生成にフォールバックします。

import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
import sidebars from "./sidebars";

export const chromeBindings = defineChromeBindings({
  sidebarsConfig: sidebars,
});

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

このリポジトリのsrc/config/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レベルフラットになります

ソート順（昇順・降順）

デフォルトでは、カテゴリ内のアイテムは昇順（sidebar_positionが小さい順、次にアルファベット順）でソートされます。カテゴリの index.mdx の category_sort_order フロントマターフィールドを使用してカテゴリごとに降順に変更できます：

---
title: Changelog
sidebar_position: 10
category_sort_order: "desc"
---

category_sort_orderが"desc"の場合、アイテムは逆順でソートされます — positionが大きい順、次に逆アルファベット順。これは日付ベースのコンテンツ（変更履歴、リリースノート）で、最新のアイテムを上部に表示したい場合に便利です。

ノートトレイでは、同じフィールドがすべての並び順を決めます。指定した向きは、サイドバー、<NoteTrayIndex>、前・次ページャー、ホームページのブロックで安定したrankを並べる向きを制御しますが、rankの値自体は変わりません。note_tray_sidebar: "year"または"month"ではグループもその向きの時系列で並び、グループ内のアイテムはrank順になります。日付グループと読み順が一致するよう、sidebar_positionはdateと同じ時系列で付けてください。詳しい設定はノートトレイを参照してください。

バインドしたサイドバー設定では、手動サイドバー設定にsortOrderを設定することもできます：

{
  type: "category",
  label: "Releases",
  sortOrder: "desc",
  items: [
    { type: "autogenerated" },
  ],
}

並び順の推奨事項

• 予測可能な順序のためにすべてのページに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に含まれている必要がありません。

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 には引き続き編集上のツリー全体が含まれるため、ツリーを広げると対象の実際の親へ、さらにその上へと移動します。親の行が重複したり、存在しない親が作られたりすることはありません。

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 に影響する場合があります。これは転送データの削減であり、プライバシー境界や表示範囲の保存方式を変更するものではありません。