サイドバー
サイドバーを作成することは、以下に役立ちます。
- 複数の関連ドキュメントをグループ化する
- それらの各ドキュメントにサイドバーを表示する
- 次/前のボタンによるページネーションナビゲーションを提供する
Docusaurusサイトでサイドバーを使用するには
- サイドバーオブジェクトの辞書をエクスポートするファイルを定義します。
- このオブジェクトを、
@docusaurus/plugin-docsプラグインに直接、または@docusaurus/preset-classic経由で渡します。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
このセクションでは、ドキュメントサイドバーのその他の機能の概要を説明します。次のセクションでは、以下の概念をより体系的に紹介します。
📄️ サイドバー項目
前のセクションの例では、autogeneratedという3つの種類の項目タイプを紹介しました。これについては後で詳しく説明します。
📄️ 自動生成
Docusaurusは、ファイルシステム構造からサイドバーを自動的に作成できます。各フォルダはサイドバーカテゴリを作成し、各ファイルはドキュメントリンクを作成します。
📄️ 複数のサイドバーの使用
グループ化するMarkdownファイルのセットごとにサイドバーを作成できます。
デフォルトのサイドバー
sidebarPathが指定されていない場合、Docusaurusはdocsフォルダのファイルシステム構造を使用して、自動的にサイドバーを生成します
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
},
],
};
サイドバーを明示的に定義することもできます。
サイドバーオブジェクト
サイドバーの中核は、カテゴリ、ドキュメントリンク、およびその他のハイパーリンクの階層です。
type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| {[categoryLabel: string]: SidebarItem[]};
たとえば
export default {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
これは、mySidebarという1つのサイドバーをエクスポートするサイドバーファイルです。これには、3つのトップレベルの項目があります。2つのカテゴリと1つの外部リンクです。各カテゴリ内には、いくつかのドキュメントリンクがあります。
サイドバーファイルには、オブジェクトキーで識別される複数のサイドバーオブジェクトを含めることができます。
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
テーマ設定
非表示可能なサイドバー
themeConfig.docs.sidebar.hideableオプションを有効にすると、サイドバー全体を非表示にすることができ、ユーザーはコンテンツに集中しやすくなります。これは、コンテンツが中程度のサイズの画面（タブレットなど）で消費される場合に特に役立ちます。
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
サイドバーカテゴリの自動折りたたみ
themeConfig.docs.sidebar.autoCollapseCategoriesオプションは、1つのカテゴリを展開すると、すべての兄弟カテゴリを折りたたみます。これにより、ユーザーは開いているカテゴリが多すぎる状態を回避し、選択したセクションに集中するのに役立ちます。
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
カスタムプロップスの渡し方
サイドバー項目にカスタムプロップスを渡すには、任意の項目にオプションのcustomPropsオブジェクトを追加します。これは、サイドバー項目をレンダリングするReactコンポーネントをスウィズリングしてサイトのカスタマイズを適用するのに役立ちます。
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
サイドバーのパンくずリスト
デフォルトでは、パンくずリストは上部にレンダリングされ、現在のページの「サイドバーパス」を使用します。
この動作は、プラグインオプションで無効にできます
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
複雑なサイドバーの例
Docusaurusサイトからの実際の例
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/toc',
'guides/markdown-features/assets',
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'swizzling',
'static-assets',
'search',
'browser-support',
'seo',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
type: 'category',
label: 'Upgrading',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: 'To Docusaurus v2',
items: [
'migration/v2/migration-overview',
'migration/v2/migration-automated',
'migration/v2/migration-manual',
'migration/v2/migration-versioned-sites',
'migration/v2/migration-translated-sites',
],
},
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;