版本: 3.5.2

自动生成

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

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

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

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

一个autogenerated条目会被 Docusaurus 转换为侧边栏切片（也在类别简写中讨论）：一个包含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', // 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 文件的提供方式。

提示

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

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

fileName，文件名称，不含扩展名，并保留大小写
directories，目录名称列表，从最低级别到最高级别，相对于文档根目录
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退出默认约定，并且不生成任何类别索引页面。

信息

position 元数据仅在侧边栏切片内使用：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,
        }) {
          // 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);
        },
      },
    ],
  ],
};

自动生成

类别索引约定

自动生成的侧边栏元数据

文档条目元数据

类别条目元数据

使用数字前缀

自定义侧边栏条目生成器

类别索引约定​

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

文档条目元数据​

类别条目元数据​

使用数字前缀​

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

类别索引约定

自动生成的侧边栏元数据

文档条目元数据

类别条目元数据

使用数字前缀

自定义侧边栏条目生成器