Pular para o conteúdo principal
Version: 2.0.1

Sidebar items

We have introduced three types of item types in the example in the previous section: doc, category, and link, whose usages are fairly intuitive. We will formally introduce their APIs. 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 para qualquer página interna ou externa
  • 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

Use o tipo doc para criar um link para uma página de documento e atribuir esse documento a uma barra lateral:

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

Exemplo:

sidebars.js
module.exports = {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document 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.

note

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

tip

Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.

Use o tipo link para vincular qualquer página (interna ou externa) que não seja um doc.

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

Exemplo:

sidebars.js
module.exports = {
  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
    },
  ],
};

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

This can be useful for inserting custom items such as dividers, section titles, ads, and images.

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

Exemplo:

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

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
module.exports = {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

Use o tipo categoria para criar uma hierarquia de itens da barra lateral.

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: 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;
};

Exemplo:

sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};
tip

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

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

With category links, clicking on a category can navigate you to another page.

tip

Use category links to introduce a category of documents.

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

Generated index page​

You can auto-generate an index page that displays all the direct children of this category. The slug allows you to customize the generated page's route, which defaults to /category/[categoryName].

sidebars.js
module.exports = {
  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'],
    },
  ],
};

See it in action on the Docusaurus Guides page.

tip

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

A category can link to an existing document.

sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      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, as long as the doc is used as a category index page. To do so, you need to use the DocCardList component, paired with the useCurrentSidebarCategory hook.

a-category-index-page.md
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

In this section, we will introduce the following concepts:

<DocCardList items={useCurrentSidebarCategory().items}/>

See this in action on the sidebar guides page.

Categorias recolhíveis​

Apoiamos a opção de expandir/recolher categorias. As categorias são recolhidas por padrão, mas você pode desabilitar a colapsão com collapsible: false.

sidebars.js
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      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
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};
note

A opção em sidebars.js tem precedência sobre a configuração do plugin, então é possível tornar certas categorias recolhíveis quando sidebarCollapsible é definido como false globalmente.

Categorias expandidas por padrão​

As categorias recolhíveis são recolhidas por padrão. If you want them to be expanded on the first render, you can set collapsed to false:

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

Semelhante a collapsible, você também pode definir a configuração global options.sidebarCollapsed como false. As opções individuais collapsed em sidebars.js ainda terão precedência sobre esta configuração.

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

Quando uma categoria tem collapsed: verdadeiro, mas collapsible: falso (seja por meio de sidebars.js ou por meio da configuração do plug-in), o último tem precedência e o a categoria ainda é processada como expandida.

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:

sidebars.js
module.exports = {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

So it's possible to simplify the example above to:

sidebars.js
module.exports = {
  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​

A category item can be represented by an object whose key is its label, and the value is an array of subitems.

sidebars.js
module.exports = {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

This permits us to simplify that example to:

sidebars.js
module.exports = {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:

sidebars.js
module.exports = {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Note how the two consecutive category shorthands are compressed into one object with two entries. 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.

Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.

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