自动生成

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

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

Docusaurus 可以根据您的 docs 文件夹生成完整的侧边栏：

sidebars.js
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' 表示当前 docs 文件夹
    },
  ],
};

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

一个真实的例子

考虑以下文件结构：

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 中的两个文件
        'easy1',
        'easy2',
        'tutorial-medium',
        // docs/tutorials/advanced 中的两个文件和一个文件夹
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // 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 文件的提供方式。

提示

如果一个文件夹只有一个索引页面，它将被转换为链接而不是类别。这对于 资产位置 很有用：

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, // 默认匹配器实现，如下所示
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex() {
              // 没有文档会被自动选择为类别索引
              return false;
            },
          });
        },
      },
    ],
  ],
};

isCategoryIndex 匹配器将提供三个字段：

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 属性分别在 front matter 中声明为 sidebar_label、sidebar_class_name 和 sidebar_custom_props。可以通过 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_.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 # 支持浮点位置
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

信息

如果显式指定了 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) ;

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

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          categoriesMetadata,
          isCategoryIndex,
        }) {
          // 示例：返回一个硬编码的静态侧边栏项目列表
          return [
            {type: 'doc', id: 'doc1'},
            {type: 'doc', id: 'doc2'},
          ];
        },
      },
    ],
  ],
};

提示

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

根据您的用例添加、更新、过滤、重新排序侧边栏项目：

docusaurus.config.js
// 反转侧边栏项目的排序（包括嵌套的类别项目）
function reverseSidebarItems(items) {
  // 反转类别中的项目
  const result = items.map((item) => {
    if (item.type === 'category') {
      return {...item, items: reverseSidebarItems(item.items)};
    }
    return item;
  });
  // 反转当前级别的项目
  result.reverse();
  return result;
}

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

自动生成

类别索引约定

自动生成侧边栏元数据

文档项目元数据

类别项目元数据

使用数字前缀

自定义侧边栏项目生成器

类别索引约定​

自动生成侧边栏元数据​

文档项目元数据​

类别项目元数据​

使用数字前缀​

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

类别索引约定

自动生成侧边栏元数据

文档项目元数据

类别项目元数据

使用数字前缀

自定义侧边栏项目生成器