バージョン: 3.5.2

自動生成

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

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};

Docusaurusは、docsフォルダから完全なサイドバーを生成できます

sidebars.js
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};

autogenerated アイテムは、Docusaurusによってサイドバースライス（カテゴリの省略形でも説明されています）に変換されます。これは、docまたはcategoryタイプのアイテムのリストであるため、複数のディレクトリから複数のautogeneratedアイテムをスプライスし、通常のサイドバーアイテムと1つのサイドバーレベルで交互に配置できます。

実際の例

このファイル構造を考えてみましょう

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── tutorial-end.md
    ├── tutorial-intro.md
    └── tutorial-medium.md

すべてのドキュメントのIDがファイル名であると仮定します。次のように自動生成されたサイドバーを定義すると

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        {
          type: 'autogenerated',
          dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
        },
        'tutorial-medium',
        {
          type: 'autogenerated',
          dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/advanced
        },
        'tutorial-end',
      ],
    },
    {
      type: 'autogenerated',
      dirName: 'api', // Generate sidebar slice from docs/api
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

次のように解決されます

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        // Two files in docs/tutorials/easy
        'easy1',
        'easy2',
        'tutorial-medium',
        // Two files and a folder in docs/tutorials/advanced
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // Two folders in docs/api
    {
      type: 'category',
      label: 'product1-api',
      items: ['api'],
    },
    {
      type: 'category',
      label: 'product2-api',
      items: ['basic-api', 'pro-api'],
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

自動生成ソースディレクトリ自体がカテゴリにならないことに注意してください。それらに含まれるアイテムのみがカテゴリになります。これが「サイドバースライス」の意味です。

カテゴリインデックスの規約

Docusaurusは、カテゴリをそのインデックスドキュメントに自動的にリンクできます。

カテゴリインデックスドキュメントは、次のファイル名規則のいずれかに従うドキュメントです

index という名前（大文字と小文字を区別しない）：docs/Guides/index.md
README という名前（大文字と小文字を区別しない）：docs/Guides/README.mdx
親フォルダと同じ名前：docs/Guides/Guides.md

これは、ドキュメントリンクを持つカテゴリを使用することと同じです

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'Guides/index'},
      items: [],
    },
  ],
};

ヒント

入門ドキュメントにREADME.mdという名前を付けると、GitHubインターフェースを使用してフォルダを参照するときに表示されますが、index.mdを使用すると、HTMLファイルの提供方法とより一致するようになります。

ヒント

フォルダにインデックスページが1つしかない場合、カテゴリではなくリンクに変換されます。これは、アセットのコロケーションに役立ちます

some-doc
├── index.md
├── img1.png
└── img2.png

カテゴリインデックスのマッチングのカスタマイズ

カテゴリインデックスの規約のいずれかをオプトアウトしたり、さらに多くの規約を定義したりすることができます。 sidebarItemsGenerator コールバックを通じて独自の isCategoryIndex マッチャーを挿入できます。たとえば、intro をカテゴリインデックスの対象となる別のファイル名として選択することもできます。

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex(doc) {
              return (
                // Also pick intro.md in addition to the default ones
                doc.fileName.toLowerCase() === 'intro' ||
                defaultCategoryIndexMatcher(doc)
              );
            },
          });
        },
      },
    ],
  ],
};

または、カテゴリインデックスの規約をまったく使用しないように選択することもできます。

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex() {
              // No doc will be automatically picked as category index
              return false;
            },
          });
        },
      },
    ],
  ],
};

isCategoryIndex マッチャーには、3つのフィールドが提供されます

fileName、拡張子なしでケーシングが保持されたファイル名
directories、docsルートディレクトリを基準とした、*最下位レベルから最上位レベルまで*のディレクトリ名のリスト
extension、ファイルの拡張子（先頭にドットが付く）

たとえば、guides/sidebar/autogenerated.md にあるドキュメントファイルの場合、マッチャーが受信するプロパティは次のとおりです。

const props = {
  fileName: 'autogenerated',
  directories: ['sidebar', 'guides'],
  extension: '.md',
};

デフォルトの実装は次のとおりです。

function isCategoryIndex({fileName, directories}) {
  const eligibleDocIndexNames = [
    'index',
    'readme',
    directories[0].toLowerCase(),
  ];
  return eligibleDocIndexNames.includes(fileName.toLowerCase());
}

手書きのサイドバー定義の場合、sidebars.js を介してサイドバーアイテムにメタデータを提供します。自動生成の場合、Docusaurusはアイテムのそれぞれのファイルからメタデータを読み取ります。さらに、デフォルトではサイドバースライス内のアイテムがアルファベット順（ファイル名とフォルダ名を使用）に生成されるため、各アイテムの相対位置を調整する場合があります。

ドキュメントアイテムのメタデータ

label、className、および customProps 属性は、フロントマターでそれぞれ sidebar_label、sidebar_class_name、および sidebar_custom_props として宣言されます。位置は、sidebar_position フロントマターを介して同じ方法で指定できます。

docs/tutorials/tutorial-easy.md
---
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---

# Easy Tutorial

This is the easy tutorial!

カテゴリアイテムのメタデータ

それぞれのフォルダに _category_.json または _category_.yml ファイルを追加します。カテゴリのメタデータと position メタデータを指定できます。リンクされたドキュメントがある場合、label、className、position、および customProps は、そのドキュメントのそれぞれの値にデフォルト設定されます。

JSON
YAML

docs/tutorials/_category_.json
{
  "position": 2.5,
  "label": "Tutorial",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Tutorial overview"
  },
  "customProps": {
    "description": "This description can be used in the swizzled DocCard"
  }
}

docs/tutorials/_category_.yml
position: 2.5 # float position is supported
label: 'Tutorial'
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
className: red
link:
  type: generated-index
  title: Tutorial overview
customProps:
  description: This description can be used in the swizzled DocCard

情報

link が明示的に指定されている場合、Docusaurusはデフォルトの規約を適用しません。

ドキュメントリンクは相対的に指定できます。たとえば、カテゴリが guides ディレクトリで生成された場合、"link": {"type": "doc", "id": "intro"} はID guides/intro に解決され、前のIDのドキュメントが存在しない場合にのみ intro にフォールバックします。

link: null を使用してデフォルトの規約をオプトアウトし、カテゴリインデックスページを生成しないこともできます。

情報

位置メタデータは、サイドバースライス内でのみ使用されます。Docusaurusは、サイドバーの他のアイテムの順序を変更しません。

番号プレフィックスの使用

自動生成されたサイドバーを順序付ける簡単な方法は、ドキュメントとフォルダに番号プレフィックスを付けることです。これにより、ファイル名でソートしたときにファイルシステムにも同じ順序で表示されます

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Advanced
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

導入を容易にするために、Docusaurusは複数の番号プレフィックスパターンをサポートしています。

デフォルトでは、DocusaurusはドキュメントID、タイトル、ラベル、およびURLパスから番号プレフィックスを削除します。

警告

追加のメタデータの使用をお勧めします.

番号プレフィックスの更新は、複数の既存のMarkdownリンクの更新が必要になる場合があるため、面倒な場合があります

docs/02-Tutorial Easy/01-First Part.md
- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);

docsプラグイン（またはプリセット）の設定で、カスタム sidebarItemsGenerator 関数を提供できます

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          categoriesMetadata,
          isCategoryIndex,
        }) {
          // Example: return an hardcoded list of static sidebar items
          return [
            {type: 'doc', id: 'doc1'},
            {type: 'doc', id: 'doc2'},
          ];
        },
      },
    ],
  ],
};

ヒント

ジェネレーターを最初から作成する代わりに、デフォルトのジェネレーターを再利用して拡張します。提供されているデフォルトのジェネレーターは250行です。

ユースケースに応じて、サイドバーアイテムを追加、更新、フィルタリング、順序変更します

docusaurus.config.js
// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
  // Reverse items in categories
  const result = items.map((item) => {
    if (item.type === 'category') {
      return {...item, items: reverseSidebarItems(item.items)};
    }
    return item;
  });
  // Reverse items at current level
  result.reverse();
  return result;
}

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        },
      },
    ],
  ],
};

自動生成

カテゴリインデックスの規約

自動生成されたサイドバーのメタデータ

ドキュメントアイテムのメタデータ

カテゴリアイテムのメタデータ

番号プレフィックスの使用

サイドバーアイテムジェネレーターのカスタマイズ

カテゴリインデックスの規約​

自動生成されたサイドバーのメタデータ​

ドキュメントアイテムのメタデータ​

カテゴリアイテムのメタデータ​

番号プレフィックスの使用​

サイドバーアイテムジェネレーターのカスタマイズ​

カテゴリインデックスの規約

自動生成されたサイドバーのメタデータ

ドキュメントアイテムのメタデータ

カテゴリアイテムのメタデータ

番号プレフィックスの使用

サイドバーアイテムジェネレーターのカスタマイズ