側邊欄項目
在前一個章節的範例中，我們介紹了三種類型的項目：doc、category 和 link，它們的用法相當直觀。接下來，我們將正式介紹他們的 API。還有一種第四類：autogenerated，我們稍後會詳細說明。
- 文件：連結到文件頁面，將其與側邊欄相關聯
- 外部連結：連結到任何內部或外部頁面
- 類別：建立側邊欄項目的下拉式選單
- 自動產生：自動產生一段側邊欄
- HTML：在項目的位置呈現完整的 HTML
- *Ref：連結到文件頁面，但不會讓項目參與導覽功能的產生
文件：連結至文件的連結
使用 doc 型態連結至文件頁面，並將該文件指定至側邊欄
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
範例
export default {
mySidebar: [
// Normal syntax:
{
type: 'doc',
id: 'doc1', // document ID
label: 'Getting started', // sidebar label
},
// Shorthand syntax:
'doc2', // document ID
],
};
如果您使用 doc 簡稱或 自動產生 側邊欄，您將喪失透過項目定義自訂側邊欄標籤的能力。但是，您可以使用該文件中的 sidebar_label Markdown 前導資訊，它比側邊欄項目中的 label 鍵具有更高的優先權。同樣地，您可以使用 sidebar_custom_props 宣告文件頁面的自訂中繼資料。
doc 項目會設定 隱含側邊欄關聯。不要將同一個文件指定至多個側邊欄：請改將類型變更為 ref。
側邊欄自訂屬性是傳播任意文件中繼資料至用戶端的一種實用方法，這樣您就可以在使用任何擷取文件物件的文件相關掛鉤時取得額外的資訊。
連結：連結至任何頁面
使用 link 類型連結至任何不是文件的頁面（內部或外部）。
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
description?: string;
};
範例
export default {
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
},
],
};
HTML：呈現自訂標記
使用 html 類型在項目的 <li> 標籤中呈現自訂 HTML。
這對於插入分隔線、區段標題、廣告和影像等自訂項目非常有用。
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // Use default menu item styles
className?: string;
};
範例
export default {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
defaultStyle: true, // Use the default menu item styling
},
],
};
選單項目已包覆在 <li> 標籤中，因此如果您的自訂項目很簡單，例如標題，只需提供字串值並使用 className 屬性為其設定樣式即可
export default {
myHtmlSidebar: [
{
type: 'html',
value: 'Core concepts',
className: 'sidebar-title',
},
],
};
類別：建立階層
使用 `category` 類型來建立側邊攔項目層級。
type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
className?: string;
description?: string;
// Category options:
collapsible: boolean; // Set the category to be collapsible
collapsed: boolean; // Set the category to be initially collapsed or open by default
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
範例
export default {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
當您不需要自訂時，請使用 簡寫語法
export default {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
類別連結
使用類別連結，按一下類別就可以導覽至另一頁面。
使用類別連結來介紹一系列的文件。
自動產生的類別可以使用 _category_.yml 檔案來宣告連結。
產生索引頁面
您可以自動產生一個索引頁面，顯示此類別的所有直接子類別。slug 讓您可以自訂產生的頁面路線，預設為 /category/[categoryName]。
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description: 'Learn about the most important Docusaurus concepts!',
slug: '/category/docusaurus-guides',
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
在 Docusaurus 指南頁面 上觀看實作方式。
使用 generated-index 連結作為快速取得入門文件的方法。
文件連結
類別可以連結到現有文件。
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
在 i18n 簡介頁面 上觀看實作方式。
將產生的索引嵌入文件頁面
您也可以使用 DocCardList 元件將產生的卡片清單嵌入一般文件頁面。它會顯示目前文件父類別的所有側邊欄項目。
import DocCardList from '@theme/DocCardList';
<DocCardList />
可折疊類別
我們支援展開/收合類別選項。類別預設為可折疊，但您可以用 collapsible: false 來停用折疊功能。
export default {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
若要使所有類別預設為不可折疊，請將 plugin-content-docs 中的 sidebarCollapsible 選項設定為 false
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
sidebars.js 中的選項優先於外掛程式組態，因此即使在全域將 sidebarCollapsible 設為 false，仍有可能使某些類別可折疊。
預設為展開的類別
可收合類別預設為收合。若您要在第一次渲染時展開這些類別，您可以將 collapsed 設定為 false
export default {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
除了 collapsible，您也可以將一般的組態 options.sidebarCollapsed 設定為 false。在 sidebars.js 中的個別 collapsed 選項仍會優先於此組態。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
當一個類別有 collapsed: true 但 collapsible: false（透過 sidebars.js 或外掛組態），後者會優先，該類別還是會渲染成展開的。
使用速記法
您可以透過速記法語法更簡潔地表示典型的側欄項目，而不需要太多自訂內容。它包含兩個部分：文件速記法和類別速記法。
文件速記法
doc 類型的項目可以是表示其 ID 的字串。
- 長格式
- 短格式
export default {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
export default {
sidebar: [
'myDoc',
],
};
因此，可以將上述範例簡化為
export default {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
'doc1',
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
'doc2',
'doc3',
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
類別速記法
類別項目可以用一個物件來表示，其金鑰是標籤，值是子項目的陣列。
- 長格式
- 短格式
export default {
sidebar: [
{
type: 'category',
label: 'Getting started',
items: ['doc1', 'doc2'],
},
],
};
export default {
sidebar: [
{
'Getting started': ['doc1', 'doc2'],
},
],
};
這允許我們將範例簡化為
export default {
mySidebar: [
{
'Getting started': ['doc1'],
},
{
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
此次轉換之後，每個速記法物件僅會包含一筆資料。現在考量下方這個進一步簡化的範例
export default {
mySidebar: [
{
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
請注意，兩個連續的類別速記法是如何壓縮成一個包含兩筆資料的物件。此語法會產生一個側欄區塊：您不應將該物件視為一個整體項目—這個物件會被解開，每個資料會變成一個個別項目，它們會與其他項目（此處為「瞭解更多」連結）連接，以形成最終的側欄層級。在討論自動產生側欄時，側欄區塊也很重要。
每當您有一個項目陣列簡化為一個類別速記法時，您也可以省略那個包覆陣列。
- 之前
- 之後
export default {
sidebar: [
{
'Getting started': ['doc1'],
Docusaurus: [
{
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
],
},
],
};
export default {
sidebar: {
'Getting started': ['doc1'],
Docusaurus: {
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
},
};