Skip to main content
Version: 3.7.0

侧边栏项目

我们在前一节的示例中介绍了三种项目类型：doc、category和link，它们的用法相当直观。我们将正式介绍它们的API。还有第四种类型：autogenerated，我们将在后面详细解释。

  • Doc: 链接到一个文档页面，将其与侧边栏关联
  • Link: 链接到任何内部或外部页面
  • Category: 创建一个侧边栏项目的下拉菜单
  • Autogenerated: 自动生成侧边栏切片
  • HTML: 在项目的位置渲染纯HTML
  • *Ref: 链接到文档页面，但不使该项目参与导航生成

使用 doc 类型链接到文档页面并将该文档分配到侧边栏：

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: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

如果您使用文档简写或自动生成的侧边栏，您将失去通过项目定义自定义侧边栏标签的能力。然而，您可以在该文档中使用sidebar_label Markdown前置内容，其优先级高于侧边栏项目中的label键。同样，您可以使用sidebar_custom_props为文档页面声明自定义元数据。

note

一个doc项目设置了一个隐式侧边栏关联。不要将同一个文档分配给多个侧边栏：将类型更改为ref。

tip

侧边栏自定义属性是一种将任意文档元数据传播到客户端的有用方式，因此您可以在使用任何获取文档对象的文档相关钩子时获取额外信息。

使用link类型链接到任何不是文档的页面（内部或外部）。

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

示例：

sidebars.js
export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

使用html类型在项目的

  • 标签内渲染自定义HTML。

    这对于插入自定义项目（如分隔符、部分标题、广告和图片）非常有用。

    type SidebarItemHtml = {
      type: 'html';
      value: string;
      defaultStyle?: boolean; // Use default menu item styles
      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
        },
      ],
    };
    tip

    菜单项已经被包裹在

  • 标签中，所以如果你的自定义项很简单，比如一个标题，只需提供一个字符串作为值，并使用className属性来设置样式：
    sidebars.js
    export default {
      myHtmlSidebar: [
        {
          type: 'html',
          value: 'Core concepts',
          className: 'sidebar-title',
        },
      ],
    };

    使用category类型来创建侧边栏项目的层次结构。

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

    当你不需要自定义时，使用简写语法：

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

    通过类别链接，点击一个类别可以将您导航到另一个页面。

    tip

    使用类别链接来介绍一类文档。

    自动生成的类别可以使用_category_.yml文件来声明链接。

    生成的索引页面​

    您可以自动生成一个索引页面，显示此类别下的所有直接子项。slug 允许您自定义生成页面的路由，默认情况下为 /category/[categoryName]。

    sidebars.js
    export default {
      docs: [
        {
          type: 'category',
          label: 'Guides',
          link: {
            type: 'generated-index',
            title: 'Docusaurus Guides',
            description: 'Learn about the most important Docusaurus concepts!',
            slug: '/category/docusaurus-guides',
            keywords: ['guides'],
            image: '/img/docusaurus.png',
          },
          items: ['pages', 'docs', 'blog', 'search'],
        },
      ],
    };

    在Docusaurus 指南页面上查看实际操作。

    tip

    使用generated-index链接作为获取介绍文档的快捷方式。

    一个类别可以链接到一个现有的文档。

    sidebars.js
    export default {
      docs: [
        {
          type: 'category',
          label: 'Guides',
          link: {type: 'doc', id: 'introduction'},
          items: ['pages', 'docs', 'blog', 'search'],
        },
      ],
    };

    在i18n 介绍页面上查看实际操作。

    在文档页面中嵌入生成的索引​

    你也可以在普通的文档页面中使用DocCardList组件嵌入生成的卡片列表。它将显示当前文档父类别的所有侧边栏项目。

    docs/sidebar/index.md
    import DocCardList from '@theme/DocCardList';

    <DocCardList />
    http://localhost:3000

    可折叠类别​

    我们支持展开/折叠类别的选项。默认情况下，类别是可折叠的，但您可以使用collapsible: false来禁用折叠功能。

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

    要使所有类别默认不可折叠，请在plugin-content-docs中将sidebarCollapsible选项设置为false：

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

    sidebars.js 中的选项优先于插件配置，因此当全局设置为 sidebarCollapsible 为 false 时，可以使某些类别可折叠。

    默认展开的类别​

    可折叠类别默认是折叠的。如果你希望它们在首次渲染时展开，可以将collapsed设置为false：

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

    类似于collapsible，你也可以将全局配置options.sidebarCollapsed设置为false。在sidebars.js中的个别collapsed选项仍然会优先于此配置。

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

    当一个类别具有collapsed: true但collapsible: false（无论是通过sidebars.js还是通过插件配置），后者优先，类别仍然呈现为展开状态。

    使用简写​

    你可以使用简写语法更简洁地表达典型的侧边栏项目，而无需太多定制。这包括两部分：文档简写和类别简写。

    文档速记​

    一个类型为 doc 的项目可以简单地是一个表示其ID的字符串：

    sidebars.js
    export default {
      sidebar: [
        {
          type: 'doc',
          id: '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',
        },
      ],
    };

    类别简写​

    一个类别项可以由一个对象表示，其键是它的标签，值是一个子项数组。

    sidebars.js
    export default {
      sidebar: [
        {
          type: 'category',
          label: 'Getting started',
          items: ['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',
        },
      ],
    };

    注意两个连续的类别简写如何被压缩成一个包含两个条目的对象。这种语法生成了一个侧边栏切片：你不应该将该对象视为一个整体项目——这个对象被展开，每个条目成为一个单独的项目，并且它们与其余的项目（在本例中为“了解更多”链接）拼接在一起，形成最终的侧边栏级别。在讨论自动生成的侧边栏时，侧边栏切片也很重要。

    无论你在哪里有一个项目数组被简化为一个类别的简写，你也可以省略那个包围的数组。

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