The docs feature provides users with a way to organize Markdown files in a hierarchical format.
Every document has a unique
id. By default, a document
id is the name of the document (without the extension) relative to the root docs directory.
greeting.md id is
guide/hello.md id is
However, the last part of the
id can be defined by user in the front matter. For example, if
guide/hello.md's content is defined as below, its final
To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the
@docusaurus/plugin-docs plugin directly or via
A sidebar object is defined like this.
Below is an example of a sidebar object. The key
docs is the id of the sidebar (can be renamed to something else) and
Getting Started is a category within the sidebar.
doc1 are both sidebar item.
Keep in mind that EcmaScript does not guarantee
You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
As the name implies,
SidebarItem is an item defined in a Sidebar. There are a few types we support:
Sidebar item type that links to a doc page. Example:
Using just the Document ID is perfectly valid as well, the following is equivalent to the above:
Note that using this type will bind the linked doc to current sidebar, this means that if you access
doc1 page, the sidebar displayed will be the sidebar this item is on. For below case,
doc1 is bounded to
Sidebar item type that links to a non-document page. Example:
Sidebar item type that links to doc without bounding it to the sidebar. Example:
This is used to add hierarchies to the sidebar:
As an example, here's how we created the subcategory for "Docs" under "Guides" in this site:
Note: it's possible to use the shorthand syntax to create nested categories:
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
If you just want the documentation feature, you can follow the instructions for a "docs-only mode":
- Set the
routeBasePathproperty of the
docusaurus.config.jsto the root of your site:
- Set up a redirect to the initial document on the home page in
src/pages/index.js, e.g. for the document
getting-started. This is needed because by default there's no page created for the root of the docs.
Now, when visiting your site, it will show your initial document instead of a landing page.
There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the
src/pages/index.js file. Follow the setup instructions on Blog-only mode.