版本：3.0.0-rc.1

自动生成侧边栏

Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // 生成侧边栏切片的源文件夹（相对文档目录）
};

Docusaurus 可以从你的 docs 文件夹中自动生成整个侧边栏：

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

An autogenerated item is converted by Docusaurus to a sidebar slice (also discussed in category shorthands): a list of items of type doc or category, so you can splice multiple autogenerated items from multiple directories, interleaving them with regular sidebar items, in one sidebar level.

A real-world example

Consider this file structure:

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

It would be resolved as:

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

Note how the autogenerate source directories themselves don't become categories: only the items they contain do. This is what we mean by "sidebar slice".

Category index convention

Docusaurus 可以自动给一个类别关联一篇索引文档。

类别索引文档的文件名符合下列条件之一：

Named as index (case-insensitive): docs/Guides/index.md
Named as README (case-insensitive): docs/Guides/README.mdx
Same name as parent folder: docs/Guides/Guides.md

This is equivalent to using a category with a doc link:

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

提示

Naming your introductory document README.md makes it show up when browsing the folder using the GitHub interface, while using index.md makes the behavior more in line with how HTML files are served.

提示

如果一个文件夹只有一个索引页，它会变成一个链接，而不是一个类别。 This is useful for asset collocation:

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

Customizing category index matching

你可以选择不使用三种类别索引惯例中的任何一种，或者也可以定义更多的惯例。 You can inject your own isCategoryIndex matcher through the sidebarItemsGenerator callback. For example, you can also pick intro as another file name eligible for automatically becoming the category index.

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

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

默认的匹配函数的实现是：

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: 简单
sidebar_class_name: green
---

# 简单教程

这里是简单教程！

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

有一种简单的给自动生成侧边栏排序的方法，就是给每个文档和文件夹添加一个数字前缀。这会让它们在文件系统按文件名排序时也是有序的：

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

自动生成侧边栏

Category index convention

Autogenerated sidebar metadata

Doc item metadata

Category item metadata

Using number prefixes

Customize the sidebar items generator

自动生成侧边栏

Category index convention​

Autogenerated sidebar metadata​

Doc item metadata​

Category item metadata​

Using number prefixes​

Customize the sidebar items generator​

Category index convention

Autogenerated sidebar metadata

Doc item metadata

Category item metadata

Using number prefixes

Customize the sidebar items generator