Sidebar
Creating a sidebar 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.
- 将文件中的 sidebar 对应的 key 在 navbar 的 docSidebar item type 中使用。
{
"themeConfig": {
"navbar": {
"items": [
{
"type": "docSidebar",
"label": "Docs",
"sidebarIds": ["mySidebar"],
"position": "left"
}
]
}
}
}
上面概述了文档侧边栏的基本用法，下面将更系统地介绍下 Sidebar items 和 Autogenerated 的概念。
Sidebar items
We have introduced three types of item types in the example above: 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
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
}
// Shorthand syntax
| string; // docId shortcut
这里的 id 表示文档唯一标识，是文档相对 docs 目录的路径统一处理成纯小写且空格替换成链接符（-）后的字符串，比如文档的路径是“Overview/Quick Start”，那 id 就是 “overview/quick-start”。
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;
};
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.
};
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 simply a string representing its ID:
{
"sidebar": [
{
"type": "doc",
"id": "myDoc"
}
]
}
{
"sidebar": ["myDoc"]
}
So it's possible 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 permits us to simplify that 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 creates a sidebar category, and each file creates 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 (also 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
以下是一个完整的复杂示例：
{
"mySidebar": [
{
"Quick Start": [
"doc1",
"doc2",
{
"type": "autogenerated",
"dirName": "intro"
}
]
},
{
"type": "autogenerated",
"dirName": "faq"
},
{
"type": "link",
"label": "Learn more",
"href": "https://example.com"
}
]
}