版本：Canary 🚧

自动生成

Docusaurus 可以从文件系统结构自动创建一个边栏:每个文件夹创建一个边栏类别，每个文件创建一个文档链接。

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

Docusaurus 可以从你的 docs 文件夹生成一个完整的侧边栏:

sidebars.js
module.exports = {
  myAutogeneratedSidebar: [
    {
      type: "autogenerated",
      dirName: ".", // '.' means the current docs folder
    },
  ],
};

一个自动生成的项目被 Docusaurus 转换为一个侧栏切片(也在category 速记中讨论):一个类型为doc或category的项目列表，所以你可以从多个目录中剪切多个自动生成的项目，将它们与常规的侧栏项目交错在一个侧栏级别。

一个现实世界的例子

考虑以下文件结构:

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
module.exports = {
  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
module.exports = {
  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 (case-insensitive): docs/Guides/index.md
命名为README (case-insensitive): docs/Guides/README.mdx
与父文件夹名称相同: docs/Guides/Guides.md

这相当于使用带有文档链接的类别:

sidebars.js
module.exports = {
  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
module.exports = {
  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
module.exports = {
  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, 相对于 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属性分别在前面声明为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文件。您可以指定任何类别元数据，也可以指定位置元数据。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来退出默认约定，不生成任何类别索引页。

信息

位置元数据仅在侧边栏切片中使用

不会重新排序侧边栏的其他项。

使用号码前缀

给自动生成的侧边栏排序的一个简单方法是给文档和文件夹加上数字前缀，这也使它们在按文件名排序时以相同的顺序出现在文件系统中:

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

你可以在 docs 插件(或预置)配置中提供一个自定义的sidebarItemsGenerator函数:

docusaurus.config.js
module.exports = {
  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;
}

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

自动生成

品类索引约定

自动生成的侧栏元数据

文档项元数据

类别项元数据

使用号码前缀

自定义侧边栏项生成器

自动生成

品类索引约定​

自动生成的侧栏元数据​

文档项元数据​

类别项元数据​

使用号码前缀​

自定义侧边栏项生成器​

品类索引约定

自动生成的侧栏元数据

文档项元数据

类别项元数据

使用号码前缀

自定义侧边栏项生成器