Manage your docs
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",
"sidebarIds": ["mySidebar"],
"position": "left"
}
]
}
}
}
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": "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.
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": "Guides",
"items": [
"creating-pages",
{
"type": "category",
"label": "Docs",
"items": [
"introduction",
"sidebar",
"markdown-features",
"versioning"
]
}
]
}
]
}
Use the shorthand syntax when you don't need customizations:
{
"mySidebar": {
"Guides": [
"creating-pages",
{
"Docs": ["introduction", "sidebar", "markdown-features", "versioning"]
}
]
}
}
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:
{
"sidebar": [
{
"type": "doc",
"id": "myDoc"
}
]
}
{
"sidebar": ["myDoc"]
}
So it's possible for you to simplify the example above to:
{
"mySidebar": [
{
"type": "category",
"label": "Getting Started",
"items": ["doc1"]
},
{
"type": "category",
"label": "Docuo",
"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.
{
"sidebar": [
{
"type": "category",
"label": "Getting started",
"items": ["doc1", "doc2"]
}
]
}
{
"sidebar": [
{
"Getting started": ["doc1", "doc2"]
}
]
}
This allows you to simplify the example to:
{
"mySidebar": [
{
"Getting started": ["doc1"]
},
{
"Docuo": ["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:
{
"mySidebar": [
{
"Getting started": ["doc1"],
"Docuo": ["doc2", "doc3"]
},
{
"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.
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": "doc1"
}
]
},
{
"type": "category",
"label": "Docuo",
"items": [
{
"type": "doc",
"id": "doc2"
},
{
"type": "doc",
"id": "doc3"
}
]
},
{
"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": [
{
"Quick Start": [
"doc1",
"doc2",
{
"type": "autogenerated",
"dirName": "intro"
}
]
},
{
"type": "autogenerated",
"dirName": "faq"
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}