Version: 3.6.1

自动生成

¥Autogenerated

Docusaurus 可以根据你的文件系统结构自动创建侧边栏：每个文件夹创建一个侧边栏类别，每个文件创建一个文档链接。

¥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; // Source folder to generate the sidebar slice from (relative to docs)
};

Docusaurus 可以从你的文档文件夹生成完整的侧边栏：

¥Docusaurus can generate a full sidebar from your docs folder:

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

Docusaurus 将 autogenerated 项目转换为侧边栏切片（也在类别简写中讨论）：类型为 doc 或 category 的项目列表，因此你可以在一个侧边栏级别中拼接多个目录中的多个 autogenerated 项目，将它们与常规侧边栏项目交错。

¥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 只是其文件名。如果你像这样定义自动生成的侧边栏：

¥And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this:

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 可以自动将类别链接到其索引文档。

¥Docusaurus can automatically link a category to its index document.

类别索引文档是遵循以下文件名约定之一的文档：

¥A category index document is a document following one of those filename conventions:

命名为 index（不区分大小写）：docs/Guides/index.md

¥Named as index (case-insensitive): docs/Guides/index.md
命名为 README（不区分大小写）：docs/Guides/README.mdx

¥Named as README (case-insensitive): docs/Guides/README.mdx
与父文件夹同名：docs/Guides/Guides.md

¥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: [],
    },
  ],
};

提示

将介绍性文档命名为 README.md 可以使其在使用 GitHub 界面浏览文件夹时显示，而使用 index.md 可以使行为更符合 HTML 文件的服务方式。

¥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.

提示

如果一个文件夹只有一个索引页，它将变成一个链接而不是类别。这对于资源配置很有用：

¥If a folder only has one index page, it will be turned into a link instead of a category. This is useful for asset collocation:

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

Customizing category index matching

可以选择退出任何类别索引约定，或者定义更多约定。你可以通过 sidebarItemsGenerator 回调注入你自己的 isCategoryIndex 匹配器。例如，你还可以选择 intro 作为另一个有资格自动成为类别索引的文件名。

¥It is possible to opt out any of the category index conventions, or define even more conventions. 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)
              );
            },
          });
        },
      },
    ],
  ],
};

或者选择不具有任何类别索引约定。

¥Or choose to not have any category index convention.

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 匹配器将提供三个字段：

¥The isCategoryIndex matcher will be provided with three fields:

fileName，不带扩展名并保留大小写的文件名

¥fileName, the file's name without extension and with casing preserved
directories，从最底层到最顶层的目录名列表，相对于 docs 根目录

¥directories, the list of directory names from the lowest level to the highest level, relative to the docs root directory
extension，文件的扩展名，带有前导点。

¥extension, the file's extension, with a leading dot.

例如，对于 guides/sidebar/autogenerated.md 处的文档文件，匹配器收到的 props 是

¥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());
}

¥Autogenerated sidebar metadata

对于手写侧边栏定义，你可以通过 sidebars.js 向侧边栏项目提供元数据；对于自动生成的，Docusaurus 将从项目各自的文件中读取它们。此外，你可能需要调整每个项目的相对位置，因为默认情况下，侧边栏切片中的项目将按字母顺序生成（使用文件和文件夹名称）。

¥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

label、className 和 customProps 属性在前面分别声明为 sidebar_label、sidebar_class_name 和 sidebar_custom_props。可以通过 sidebar_position 前面的内容以相同的方式指定位置。

¥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

在相应的文件夹中添加 _category_.json 或 _category_.yml 文件。你可以指定任何类别元数据以及 position 元数据。label、className、position 和 customProps 将默认为类别链接文档的相应值（如果有）。

¥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

信息

如果明确指定 link，Docusaurus 将不会应用任何默认约定。

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

文档链接可以相对指定，例如如果类别是使用 guides 目录生成的，则 "link": {"type": "doc", "id": "intro"} 将解析为 ID guides/intro，只有在具有前一个 ID 的文档不存在时才会回退到 intro。

¥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.

你还可以使用 link: null 选择退出默认约定，并且不生成任何类别索引页。

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

信息

位置元数据仅在侧边栏切片中使用：Docusaurus 不会重新排序侧边栏的其他项目。

¥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

为了更容易采用，Docusaurus 支持多种数字前缀模式。

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

默认情况下，Docusaurus 将从文档 ID、标题、标签和 URL 路径中删除数字前缀。

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

警告

更喜欢使用附加元数据。

¥Prefer using additional metadata.

更新号码前缀可能很烦人，因为它可能需要更新多个现有的 Markdown 链接：

¥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);

¥Customize the sidebar items generator

你可以在文档插件（或预设）配置中提供自定义 sidebarItemsGenerator 函数：

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

提示

重用并增强默认生成器，而不是从头开始编写生成器：我们提供的默认生成器的长度为 250 行。

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

自动生成

类别索引约定

自动生成的侧边栏元数据

文档项元数据

类别项目元数据

使用数字前缀

自定义侧边栏项目生成器

类别索引约定​

自动生成的侧边栏元数据​

文档项元数据​

类别项目元数据​

使用数字前缀​

自定义侧边栏项目生成器​

类别索引约定

自动生成的侧边栏元数据

文档项元数据

类别项目元数据

使用数字前缀

自定义侧边栏项目生成器