侧边栏项目

We have introduced three types of item types in the example in the previous section: doc, category, and link, whose usages are fairly intuitive. 我们会正式介绍它们的 API。 There's also a fourth type: autogenerated, which we will explain in detail later.

• Doc: link to a doc page, associating it with the sidebar
• Link: link to any internal or external page
• Category: creates a dropdown of sidebar items
• Autogenerated: generate a sidebar slice automatically
• HTML: renders pure HTML in the item's position
• *Ref: link to a doc page, without making the item take part in navigation generation

Doc: link to a doc

Use the doc type to link to a doc page and assign that doc to a sidebar:

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

示例：

sidebars.js

export default {
  mySidebar: [
    // 常规语法：
    {
      type: 'doc',
      id: 'doc1', // 文档 ID
      label: 'Getting started', // 侧边栏标签
    },

    // 简写语法：
    'doc2', // 文档 ID
  ],
};

If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label Markdown front matter within that doc, which has higher precedence over the label key in the sidebar item. Similarly, you can use sidebar_custom_props to declare custom metadata for a doc page.

备注

A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref instead.

提示

如果想要向客户端传送任意文档元数据，侧边栏自定义属性是个不错的方式，这样你就可以在使用钩子函数时，在返回的文档对象上获得额外的信息了。

Link: link to any page

Use the link type to link to any page (internal or external) that is not a doc.

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  description?: string;
};

示例：

sidebars.js

export default {
  myLinksSidebar: [
    // 外部链接
    {
      type: 'link',
      label: 'Facebook', // 链接标签
      href: 'https://facebook.com', // 外部 URL
    },

    // 内部链接
    {
      type: 'link',
      label: 'Home', // 链接标签
      href: '/', // 内部路径
    },
  ],
};

HTML: render custom markup

Use the html type to render custom HTML within the item's <li> tag.

适用于插入自定义项目，比如分割线、节标题、广告、图片。

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // 使用默认的菜单项目样式
  className?: string;
};

示例：

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

提示

The menu item is already wrapped in an <li> tag, so if your custom item is simple, such as a title, just supply a string as the value and use the className property to style it:

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

Category: create a hierarchy

Use the category type to create a hierarchy of sidebar items.

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

示例：

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

提示

Use the shorthand syntax when you don't need customizations:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

Category links

使用类别链接，让点击类别标签可以跳转到另一个页面。

提示

用类别链接来做一组文档的引言。

Autogenerated categories can use the _category_.yml file to declare the link.

Generated index page

你可以自动生成一个索引页，显示此类别的所有直接子项。 The slug allows you to customize the generated page's route, which defaults to /category/[categoryName].

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: '教程',
      link: {
        type: 'generated-index',
        title: 'Docusaurus 教程',
        description: '学习最重要的 Docusaurus 概念!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

See it in action on the Docusaurus Guides page.

提示

Use generated-index links as a quick way to get an introductory document.

Doc link

类别链接可以指向现有的文档。

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: '教程',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

See it in action on the i18n introduction page.

Embedding generated index in doc page

You can embed the generated cards list in a normal doc page as well with the DocCardList component. 它会显示当前文档所属类别的所有侧边栏项目。

docs/sidebar/index.md

import DocCardList from '@theme/DocCardList';

<DocCardList />

http://localhost:3000

📄️ 侧边栏项目

We have introduced three types of item types in the example in the previous section autogenerated, which we will explain in detail later.

📄️ 自动生成侧边栏

Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.

📄️ 使用多个侧边栏

You can create a sidebar for each set of Markdown files that you want to group together.

Collapsible categories

我们支持设置展开/折叠分类。 Categories are collapsible by default, but you can disable collapsing with collapsible: false.

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: '教程',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

To make all categories non-collapsible by default, set the sidebarCollapsible option in plugin-content-docs to false:

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

备注

The option in sidebars.js takes precedence over plugin configuration, so it is possible to make certain categories collapsible when sidebarCollapsible is set to false globally.

Expanded categories by default

可折叠菜单默认被折叠。 If you want them to be expanded on the first render, you can set collapsed to false:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

Similar to collapsible, you can also set the global configuration options.sidebarCollapsed to false. Individual collapsed options in sidebars.js will still take precedence over this configuration.

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

警告

When a category has collapsed: true but collapsible: false (either through sidebars.js or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.

Using shorthands

You can express typical sidebar items without much customization more concisely with shorthand syntaxes. There are two parts to this: doc shorthand and category shorthand.

Doc shorthand

An item with type doc can be simply a string representing its ID:

Longhand

sidebars.js

export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

Shorthand

sidebars.js

export default {
  sidebar: [
    'myDoc',
  ],
};

所以可以把上面的例子简化成：

sidebars.js

export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Category shorthand

一个类别可以用一个对象代替，对象的键是它的标签，值是它的子项目的列表。

Longhand

sidebars.js

export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

Shorthand

sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1', 'doc2'],
    },
  ],
};

这允许我们把上面的例子简化成：

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

在这一步转换之后，每一个简写的对象都会包括恰好一个键值对。 现在，考虑下面这个进一步简化的例子：

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

注意到连续的两个类别简写被压缩成了一个有两个键值对的对象。 This syntax generates a sidebar slice: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing autogenerated sidebars.

只要你有一个项目数组最终被缩减到了一个类别简写，你都可以略去外面的数组方括号。

Before

sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};

After

sidebars.js

export default {
  sidebar: {
    'Getting started': ['doc1'],
    Docusaurus: {
      'Basic guides': ['doc2', 'doc3'],
      'Advanced guides': ['doc4', 'doc5'],
    },
  },
};