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 to any internal or external page
- Category: creates a dropdown of sidebar items
- Autogenerated: generate a sidebar slice automatically
- *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
}
// Shorthand syntax
| string; // docId shortcut
Example:
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.
note
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;
};
Example:
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
},
],
};
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;
// 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;
};
Example:
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:
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
Category links
With category links, clicking on a category can navigate you to another page.
tip
Use category links to introduce a category of documents.
Doc link
A category can link to an existing document.
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.
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].
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',
},
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.
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.
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.
Collapsible categories
We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with collapsible: false.
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:
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
note
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
Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set collapsed to false:
module.exports = {
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.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
caution
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:
// =================
// This item:
// =================
{
type: 'doc',
id: 'myDoc',
};
// =================
// Is equivalent to:
// =================
'myDoc';
So it's possible to simplify the example above to:
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.
// ===================
// This item:
// ===================
{
type: 'category',
label: 'Getting started',
items: ['doc1', 'doc2'],
};
// ===================
// Is equivalent to:
// ===================
{
'Getting started': ['doc1', 'doc2'],
};
This permits us to simplify that example to:
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:
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.