自动生成

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

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', // 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 属性分别在 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

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"
  }
}

YAML

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 来禁用默认约定，并且不生成任何类别索引页面。

信息

位置元数据仅在侧边栏片段内使用：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);
        },
      },
    ],
  ],
};