侧边栏项目
We have introduced three types of item types in the example in the previous section: doc
, category
, and link
, whose usages are fairly intuitive. 我们会正式介绍它们的 API。 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
- HTML: renders pure HTML in the item's position
- *Ref: link to a doc page, without making the item take part in navigation generation
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
className?: string; // Class name for sidebar label
customProps?: Record<string, unknown>; // Custom props
}
// Shorthand syntax
| string; // docId shortcut
示例:
module.exports = {
mySidebar: [
// 普通语法:
{
type: 'doc',
id: 'doc1', // 文档 ID
label: 'Getting started', // 侧边栏标签
},
// 简写语法:
'doc2', // 文档 ID
],
};
If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label
Markdown front matter within that doc, which has higher precedence over the label
key in the sidebar item. Similarly, you can use sidebar_custom_props
to declare custom metadata for a doc page.
A doc
item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref
instead.
如果想要向客户端传送任意文档元数据,侧边栏自定义属性是个不错的方式,这样你就可以在使用钩子函数时,在返回的文档对象上获得额外的信息了。
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;
className?: string;
description?: string;
};
示例:
module.exports = {
myLinksSidebar: [
// 外部链接
{
type: 'link',
label: 'Facebook', // 链接标签
href: 'https://facebook.com', // 外部 URL
},
// 内部链接
{
type: 'link',
label: 'Home', // 链接标签
href: '/', // 内部路径
},
],
};
HTML: render custom markup
Use the html
type to render custom HTML within the item's <li>
tag.
适用于插入自定义项目,比如分割线、节标题、广告、图片。
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // 使用默认的菜单项目样式
className?: string;
};
示例:
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
defaultStyle: true, // Use the default menu item styling
},
],
};
The menu item is already wrapped in an <li>
tag, so if your custom item is simple, such as a title, just supply a string as the value and use the className
property to style it:
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '核心概念',
className: 'sidebar-title',
},
],
};