Sidebar
You can configure a sidebar to manage your documentation, which is useful to:
- Group multiple related documents
- Display a sidebar on each of those documents
To use sidebars on your Docuo site:
- Define a file that contains a dictionary of sidebar objects.
- Use the sidebar key in the file in
docSidebaritem type of navbar.
{
"themeConfig": {
"navbar": {
"items": [
{
"type": "docSidebar",
"label": "Docs",
"sidebarId": "mySidebar",
"position": "left"
}
]
}
}
}
{
"mySidebar": [
{
"type": "category",
"label": "Overview",
"items": ["overview/introduction"]
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}
Sidebar items
There are four types of sidebar items including doc, category, link, and autogenerated.
| Item | Rendered Output |
|---|---|
| Doc | Link to a doc page, associating it with the sidebar |
| Link | Link to any internal or external page |
| Category | Create a dropdown of sidebar items |
| Autogenerated | Generate a sidebar slice automatically |
Doc: link to a doc
Use the doc type to link to a doc page and assign the doc to a sidebar:
type SidebarItemDoc =
// Normal syntax
| {
type: "doc";
id: string;
label: string; // Sidebar label text
}
// Shorthand syntax
| string; // docId shortcut
id represents the unique identifier of a doc page, which is a string generated from the path of the doc page relative to the docs directory. The string is uniformly processed into pure lowercase, and spaces are replaced with -
Here's an example:
{
"mySidebar": [
// Normal syntax
{
"type": "doc",
"id": "overview/basic-features", // document ID
"label": "Basic features" // sidebar label
},
// Shorthand syntax
"overview/introduction" // document ID
]
}
If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition.
A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars.
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;
};
Here's an example:
{
"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.
};
Here's an example:
{
"mySidebar": [
{
"type": "category",
"label": "Editing docs",
"items": [
"editing-docs/docs-components",
{
"type": "category",
"label": "Managing docs",
"items": [
"editing-docs/managing-docs/sidebar",
]
}
]
}
]
}
Use the shorthand syntax when you don't need customizations:
{
"mySidebar": {
"Editing docs": [
"editing-docs/docs-components",
{
"Managing docs": ["editing-docs/managing-docs/sidebar"]
}
]
}
}
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 simplified to a string to represent its ID:
{
"mySidebar": [
{
"type": "doc",
"id": "overview/introduction"
}
]
}
{
"mySidebar": ["overview/introduction"]
}
So it's possible for you to simplify the example above to:
{
"mySidebar": [
{
"type": "category",
"label": "Overview",
"items": ["overview/introduction"]
},
{
"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.
{
"mySidebar": [
{
"type": "category",
"label": "Overview",
"items": ["overview/introduction", "overview/basic-features"]
}
]
}
{
"mySidebar": [
{
"Overview": ["overview/introduction", "overview/basic-features"]
}
]
}
This allows you to simplify the example to:
{
"mySidebar": [
{
"Overview": ["overview/introduction"]
},
{
"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:
{
"mySidebar": [
{
"Overview": ["overview/introduction"],
"Getting started": ["getting-started/quickstart", "getting-started/development"]
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}
Autogenerated
Docuo can create a sidebar automatically from your filesystem structure: each folder represents a sidebar category, and each file generates a doc link.
type SidebarItemAutogenerated = {
type: "autogenerated";
dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};
Docuo can generate a full sidebar from your docs folder:
{
"myAutogeneratedSidebar": [
{
"type": "autogenerated",
"dirName": "." // "." means the current docs folder
}
]
}
An autogenerated item is converted by Docuo to a sidebar slice (discussed in category shorthand): a list of items of type doc or category. So you can splice multiple autogenerated items from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
Using number prefixes
A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name:
docs
├── 01-Overview
│ ├── 01-Introduction.mdx
│ └── 02-Basic features.mdx
└── 02-Getting started
├── 01-Quickstart.mdx
├── 02-Development.mdx
├── 03-Set up your first project.mdx
└── 04-Configuration.mdx
By default, Docuo will remove the number prefix from the doc id, title, label, and URL paths. This means that you do not need to type the prefix when using it.
For example:
[Check the Quickstart](../../getting-started/quickstart.mdx)
When setting the dirName field, you need to type the full file path, and cannot ignore the numeric prefix. Since it's not part of the Docuo internal file system, it's just used to generate directories.
Default sidebar
If the sidebarPath is unspecified, Docuo automatically use a default sidebar for you by using the filesystem structure of the docs folder:
{
"mySidebar": [
{
"type": "autogenerated",
"dirName": "." // generate sidebar from the docs folder
}
]
}
You can also define your sidebars explicitly.
Sidebar object
A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.
type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| { [categoryLabel: string]: SidebarItem[] };
For example:
{
"mySidebar": [
{
"type": "category",
"label": "Getting Started",
"items": [
{
"type": "doc",
"id": "getting-started/quickstart"
}
]
},
{
"type": "category",
"label": "Overview",
"items": [
{
"type": "doc",
"id": "overview/introduction"
},
{
"type": "doc",
"id": "overview/basic-features"
}
]
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}
This is a sidebars file that exports one sidebar, called mySidebar. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.
Complex sidebars example
Here's an complete example with complex sidebar usage:
{
"mySidebar": [
{
"Editing docs": [
"editing-docs/docs-components",
{
"type": "autogenerated",
"dirName": "Managing docs"
}
]
},
{
"type": "autogenerated",
"dirName": "Overview"
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}