自動生成

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

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // サイドバーのスライスを生成する元フォルダー（docsフォルダーからの相対パス）
};

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

sidebars.js
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' は現在の docs フォルダーを指します
    },
  ],
};

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', // docs/tutorials/easy からサイドバースライスを生成
        },
        'tutorial-medium',
        {
          type: 'autogenerated',
          dirName: 'tutorials/advanced', // docs/tutorials/advanced からサイドバースライスを生成
        },
        'tutorial-end',
      ],
    },
    {
      type: 'autogenerated',
      dirName: 'api', // docs/api からサイドバースライスを生成
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

次のように解決されます：

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        // docs/tutorials/easy 内の2つのファイル
        'easy1',
        'easy2',
        'tutorial-medium',
        // docs/tutorials/advanced 内の2つのファイルと1つのフォルダ
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // docs/api 内の2つのフォルダ
    {
      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, // 以下に示すデフォルトのマッチャー実装
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex(doc) {
              return (
                // デフォルトのファイルに加えて intro.md も選択する
                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;
            },
          });
        },
      },
    ],
  ],
};

The isCategoryIndex matcher will be provided with three fields:

fileName, the file's name without extension and with casing preserved
directories, the list of directory names from the lowest level to the highest level, relative to the docs root directory
extension, the file's extension, with a leading dot.

For example, for a doc file at guides/sidebar/autogenerated.md, the props the matcher receives are

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

The default implementation is:

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

For handwritten sidebar definitions, you would provide metadata to sidebar items through sidebars.js; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in alphabetical order (using file and folder names).

Doc item metadata

The label, className, and customProps attributes are declared in front matter as sidebar_label, sidebar_class_name, and sidebar_custom_props, respectively. Position can be specified in the same way, via sidebar_position front matter.

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

# Easy Tutorial

This is the easy tutorial!

Category item metadata

Add a _category_.json or _category_.yml file in the respective folder. You can specify any category metadata and also the position metadata. label, className, position, and customProps will default to the respective values of the category's linked doc, if there is one.

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

情報

If the link is explicitly specified, Docusaurus will not apply any default conventions.

The doc links can be specified relatively, e.g. if the category is generated with the guides directory, "link": {"type": "doc", "id": "intro"} will be resolved to the ID guides/intro, only falling back to intro if a doc with the former ID doesn't exist.

You can also use link: null to opt out of default conventions and not generate any category index page.

情報

The position metadata is only used within a sidebar slice: Docusaurus does not re-order other items of your sidebar.

Using number prefixes

A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name:

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

To make it easier to adopt, Docusaurus supports multiple number prefix patterns.

By default, Docusaurus will remove the number prefix from the doc id, title, label, and URL paths.

警告

Prefer using additional metadata.

Updating a number prefix can be annoying, as it can require updating multiple existing Markdown links:

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

You can provide a custom sidebarItemsGenerator function in the docs plugin (or preset) config:

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'},
          ];
        },
      },
    ],
  ],
};

ヒント

Re-use and enhance the default generator instead of writing a generator from scratch: the default generator we provide is 250 lines long.

Add, update, filter, re-order the sidebar items according to your use case:

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);
        },
      },
    ],
  ],
};

自動生成

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

Autogenerated sidebar metadata

Doc item metadata

Category item metadata

Using number prefixes

Customize the sidebar items generator

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

Autogenerated sidebar metadata​

Doc item metadata​

Category item metadata​

Using number prefixes​

Customize the sidebar items generator​

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

Autogenerated sidebar metadata

Doc item metadata

Category item metadata

Using number prefixes

Customize the sidebar items generator