バージョン: 3.5.2

サイドバー項目

前のセクションの例では、3つの種類の項目タイプ（doc、category、link）を紹介しました。これらの使い方は非常に直感的です。ここでは、これらのAPIを正式に紹介します。また、4つ目のタイプとして、autogeneratedというものがありますが、これについては後で詳しく説明します。

ドキュメント (Doc): ドキュメントページへのリンクで、サイドバーと関連付けます
リンク (Link): 内部または外部の任意のページへのリンク
カテゴリ (Category): サイドバー項目のドロップダウンを作成します
自動生成 (Autogenerated): サイドバースライスを自動的に生成します
HTML: 項目の位置に純粋なHTMLをレンダリングします
参照 (Ref): ナビゲーション生成に参加せずにドキュメントページへのリンクを作成します

doc タイプを使用してドキュメントページにリンクし、そのドキュメントをサイドバーに割り当てます

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

例

sidebars.js
export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

ドキュメントの省略形または自動生成されたサイドバーを使用すると、項目の定義を通じてサイドバーラベルをカスタマイズする機能が失われます。ただし、そのドキュメント内で sidebar_label Markdownフロントマターを使用できます。これは、サイドバー項目の label キーよりも優先されます。同様に、sidebar_custom_props を使用して、ドキュメントページのカスタムメタデータを宣言できます。

注意

doc 項目は暗黙のサイドバー関連付けを設定します。同じドキュメントを複数のサイドバーに割り当てないでください。代わりに、タイプを ref に変更してください。

ヒント

サイドバーカスタムプロパティは、任意のドキュメントメタデータをクライアント側に伝播するのに役立ちます。これにより、ドキュメントオブジェクトを取得するドキュメント関連のフックを使用する際に、追加の情報を取得できます。

ドキュメントではない任意のページ（内部または外部）にリンクするには、link タイプを使用します。

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  description?: string;
};

例

sidebars.js
export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

項目の <li> タグ内にカスタムHTMLをレンダリングするには、html タイプを使用します。

これは、区切り線、セクションタイトル、広告、画像などのカスタムアイテムを挿入するのに役立ちます。

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

例

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

ヒント

メニュー項目は既に <li> タグでラップされているため、タイトルなどのカスタム項目が単純な場合は、値を文字列として指定し、className プロパティを使用してスタイルを設定するだけです

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

サイドバー項目の階層を作成するには、category タイプを使用します。

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

例

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

ヒント

カスタマイズが不要な場合は、省略形構文を使用します

sidebars.js
export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

カテゴリリンク

カテゴリリンクを使用すると、カテゴリをクリックすると別のページに移動できます。

ヒント

ドキュメントのカテゴリを導入するには、カテゴリリンクを使用します。

自動生成されたカテゴリは、_category_.yml ファイルを使用してリンクを宣言できます。

生成されたインデックスページ

このカテゴリのすべての子を直接表示するインデックスページを自動生成できます。slug を使用すると、生成されたページのルートをカスタマイズできます。デフォルトでは、/category/[categoryName] になります。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

Docusaurusガイドページで動作を確認してください。

ヒント

導入ドキュメントをすばやく取得するには、generated-index リンクを使用します。

ドキュメントリンク

カテゴリは、既存のドキュメントにリンクできます。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

i18nの紹介ページで動作を確認してください。

ドキュメントページに生成されたインデックスを埋め込む

DocCardList コンポーネントを使用すると、生成されたカードリストを通常のドキュメントページにも埋め込むことができます。現在のドキュメントの親カテゴリのすべてのサイドバー項目が表示されます。

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />

http://localhost:3000

📄️ サイドバー項目

前のセクションの例では、3つの種類の項目タイプを紹介しました。自動生成については、後で詳しく説明します。

📄️ 自動生成

Docusaurusは、ファイルシステムの構造からサイドバーを自動的に作成できます。各フォルダーはサイドバーカテゴリを作成し、各ファイルはドキュメントリンクを作成します。

📄️ 複数のサイドバーの使用

グループ化するMarkdownファイルのセットごとにサイドバーを作成できます。

折りたたみ可能なカテゴリ

カテゴリの展開/折りたたみのオプションをサポートしています。カテゴリはデフォルトで折りたたみ可能ですが、collapsible: false を使用して折りたたみを無効にすることができます。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

すべてのカテゴリをデフォルトで折りたたみ不可にするには、plugin-content-docs の sidebarCollapsible オプションを false に設定します

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

注意

sidebars.js のオプションはプラグイン構成よりも優先されるため、sidebarCollapsible がグローバルに false に設定されている場合でも、特定のカテゴリを折りたたみ可能にすることができます。

デフォルトで展開されたカテゴリ

折りたたみ可能なカテゴリは、デフォルトで折りたたまれています。最初のレンダリングで展開したい場合は、collapsed を false に設定できます

sidebars.js
export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

collapsible と同様に、グローバル設定 options.sidebarCollapsed を false に設定することもできます。sidebars.js の個別の collapsed オプションは、この構成よりも優先されます。

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

警告

カテゴリに collapsed: true があり、collapsible: false（sidebars.js またはプラグイン構成のいずれかによって）がある場合、後者が優先され、カテゴリは展開された状態でレンダリングされます。

省略形の使用

省略形構文を使用すると、カスタマイズをあまり必要としない一般的なサイドバー項目をより簡潔に表現できます。これには、ドキュメント省略形とカテゴリ省略形の2つの部分があります。

ドキュメント省略形

doc タイプの項目は、IDを表す文字列で簡単に表現できます

詳細な記述
省略形

sidebars.js
export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

sidebars.js
export default {
  sidebar: [
    'myDoc',
  ],
};

したがって、上記の例を次のように簡略化できます

sidebars.js
export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

カテゴリ省略形

カテゴリ項目は、キーがそのラベルであり、値がサブ項目の配列であるオブジェクトで表現できます。

詳細な記述
省略形

sidebars.js
export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

sidebars.js
export default {
  sidebar: [
    {
      'Getting started': ['doc1', 'doc2'],
    },
  ],
};

これにより、この例を以下のように単純化できます。

sidebars.js
export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

この変換後の各短縮形オブジェクトには、エントリが1つだけ含まれます。次に、さらに単純化した以下の例を検討してください。

sidebars.js
export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

連続する2つのカテゴリ短縮形が、2つのエントリを持つ1つのオブジェクトに圧縮されていることに注目してください。この構文は、サイドバーのスライスを生成します。このオブジェクトを1つのバルク項目として捉えるべきではありません。このオブジェクトは展開され、各エントリが個別の項目になり、残りの項目（この場合は「さらに詳しく」リンク）と組み合わされて、最終的なサイドバーのレベルを形成します。サイドバーのスライスは、自動生成されたサイドバーを議論する際にも重要です。

1つのカテゴリ短縮形に縮小される項目の配列がある場合、その囲み配列も省略できます。

変更前
変更後

sidebars.js
export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};

sidebars.js
export default {
  sidebar: {
    'Getting started': ['doc1'],
    Docusaurus: {
      'Basic guides': ['doc2', 'doc3'],
      'Advanced guides': ['doc4', 'doc5'],
    },
  },
};

サイドバー項目

ドキュメント: ドキュメントへのリンク

リンク: 任意のページへのリンク

HTML: カスタムマークアップのレンダリング

カテゴリ: 階層の作成

カテゴリリンク

生成されたインデックスページ

ドキュメントリンク

ドキュメントページに生成されたインデックスを埋め込む

📄️ サイドバー項目

📄️ 自動生成

📄️ 複数のサイドバーの使用

折りたたみ可能なカテゴリ

デフォルトで展開されたカテゴリ

省略形の使用

ドキュメント省略形

カテゴリ省略形

ドキュメント: ドキュメントへのリンク​

リンク: 任意のページへのリンク​

HTML: カスタムマークアップのレンダリング​

カテゴリ: 階層の作成​

カテゴリリンク​

生成されたインデックスページ​

ドキュメントリンク​

ドキュメントページに生成されたインデックスを埋め込む​

📄️ サイドバー項目

📄️ 自動生成

📄️ 複数のサイドバーの使用

折りたたみ可能なカテゴリ​

デフォルトで展開されたカテゴリ​

省略形の使用​

ドキュメント省略形​

カテゴリ省略形​

ドキュメント: ドキュメントへのリンク

リンク: 任意のページへのリンク

HTML: カスタムマークアップのレンダリング

カテゴリ: 階層の作成

カテゴリリンク

生成されたインデックスページ

ドキュメントリンク

ドキュメントページに生成されたインデックスを埋め込む

折りたたみ可能なカテゴリ

デフォルトで展開されたカテゴリ

省略形の使用

ドキュメント省略形

カテゴリ省略形