Creating a sidebar is useful to:
- Group multiple related documents
- Display a sidebar on each of those documents
- Provide a paginated navigation, with next/previous button
To use sidebars on your Docusaurus site:
- Define a file that exports a sidebar object.
- Pass this object into the
@docusaurus/plugin-docsplugin directly or via
By default, Docusaurus automatically generates a sidebar for you, by using the filesystem structure of the
You can also define your sidebars explicitly.
A sidebar is a tree of sidebar items.
A sidebars file can contain multiple sidebar objects.
Notice the following:
- There is a single sidebar
mySidebar, containing 5 sidebar items
Docusaurusare sidebar categories
doc3are sidebar documents
Use the shorthand syntax to express this sidebar more concisely:
You can create a sidebar for each set of markdown files that you want to group together.
apiSidebar are sidebar technical ids and do not matter much.
tutorialSidebarwill be displayed
apiSidebarwill be displayed
A paginated navigation link documents inside the same sidebar with next and previous buttons.
SidebarItem is an item defined in a Sidebar tree.
There are different types of sidebar items:
- Doc: link to a doc page, assigning it to the sidebar
- Ref: link to a doc page, without assigning it to the sidebar
- Link: link to any internal or external page
- Category: create a hierarchy of sidebar items
- Autogenerated: generate a sidebar slice automatically
doc type to link to a doc page and assign that doc to a sidebar:
sidebar_label markdown frontmatter has a higher precedence over the
label key in
Don't assign the same doc to multiple sidebars: use a ref instead.
ref type to link to a doc page without assigning it to a sidebar.
doc1, Docusaurus will not display the
link type to link to any page (internal or external) that is not a doc.
category type to create a hierarchy of sidebar items.
Use the shorthand syntax when you don't need category options:
For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category.
autogenerated item is converted by Docusaurus to a sidebar slice: a list of items of type
Docusaurus can generate a sidebar from your docs folder:
You can also use multiple
autogenerated items in a sidebar, and interleave them with regular sidebar items:
By default, the sidebar slice will be generated in alphabetical order (using files and folders names).
If the generated sidebar does not look good, you can assign additional metadatas to docs and categories.
For docs: use additional frontmatter:
For categories: add a
_category_.yml file in the appropriate folder:
The position metadata is only used inside a sidebar slice: Docusaurus does not re-order other items of your sidebar.
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes:
To make it easier to adopt, Docusaurus supports multiple number prefix patterns.
By default, Docusaurus will remove the number prefix from the doc id, title, label and url paths.
Prefer using additional metadatas.
Updating a number prefix can be annoying, as it can require updating multiple existing markdown links:
You can provide a custom
sidebarItemsGenerator function in the docs plugin (or preset) config:
Re-use and enhance the default generator instead of writing a generator from scratch.
Add, update, filter, re-order the sidebar items according to your use-case:
Using the enabled
themeConfig.hideableSidebar option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
To pass in custom props to a swizzled sidebar item, add the optional
customProps object to any of the items:
Real-world example from the Docusaurus site: