側邊欄

建立側邊欄有助於

• 群組多個相關文件
• 在這些文件中顯示側邊欄
• 提供分頁導覽，附有上一步／下一步按鈕

要在您的 Docusaurus 網站上使用側邊欄

1. 定義一個檔案，用於匯出 側邊欄物件 字典。
2. 直接或透過 @docusaurus/preset-classic 將此物件傳遞到 @docusaurus/plugin-docs 外掛程式。

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};

本節是文件側邊欄各式功能的概觀。在以下各節中，我們將更有系統地介紹以下概念

📄️ 側邊欄項目

我們在上節的範例中介紹了三種類型，我們將在稍後詳細說明其中自動產生的部分。

📄️ 自動產生

Docusaurus 可以自動根據您的檔案系統結構建立側邊欄：每個資料夾建立一個側邊欄類別，每個檔案建立一個文件連結。

📄️ 使用多個側邊欄

您可以為每組要群組在一起的 Markdown 檔案建立一個側邊欄。

預設側邊攔

如果未指定 sidebarPath，Docusaurus 會透過使用 docs 資料夾的檔案系統架構，自動產生側邊攔

sidebars.js

export default {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};

你也可以明確定義側邊欄。

側邊欄物件

側邊欄的關鍵在於分類、文件連結和其它超連結的層級

type Sidebar =
  // Normal syntax
  | SidebarItem[]
  // Shorthand syntax
  | {[categoryLabel: string]: SidebarItem[]};

例如

sidebars.js

export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        {
          type: 'doc',
          id: 'doc1',
        },
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        {
          type: 'doc',
          id: 'doc2',
        },
        {
          type: 'doc',
          id: 'doc3',
        },
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

此為匯出一個名為 mySidebar 的側邊欄的側邊欄檔案。它有三個頂層項目：兩個分類和一個外部連結。每個分類中有幾個文件連結。

側邊欄檔案可以包含 多個側邊欄物件，它們的物件金鑰會將它們識別出來。

type SidebarsFile = {
  [sidebarID: string]: Sidebar;
};

佈景主題組態

可隱藏的側邊欄

透過啟用 themeConfig.docs.sidebar.hideable 選項，你可以讓整個側邊欄都可以隱藏，讓使用者可以更專注於內容。這在中型螢幕（例如平板電腦）上瀏覽內容時特別有用。

docusaurus.config.js

export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

自動收合側邊欄分類

當展開一個分類時，themeConfig.docs.sidebar.autoCollapseCategories 選項會收合所有同層級分類。這可減少使用者同時開啟的分類數量，且能幫助他們專注於所選的區段。

docusaurus.config.js

export default {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

傳遞自訂道具

若要將自訂道具傳遞至側邊欄項目，請將選擇的 customProps 物件新增至任何項目。這可以用於透過轉換顯示側邊欄項目的 React 元件來套用網站自訂。

{
  type: 'doc',
  id: 'doc1',
  customProps: {
    badges: ['new', 'green'],
    featured: true,
  },
};

側邊欄麵包屑

預設情況下，麵包屑會顯示在最上方，使用當前頁面的「側邊欄路徑」。

此行為可以透過外掛程式選項關閉

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false,
        },
      },
    ],
  ],
};

複雜側邊欄範例

Docusaurus 網站中的實際範例

sidebars.js

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
  docs: [
    'introduction',
    {
      type: 'category',
      label: 'Getting Started',
      link: {
        type: 'generated-index',
      },
      collapsed: false,
      items: [
        'installation',
        'configuration',
        'playground',
        'typescript-support',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description:
          "Let's learn about the most important Docusaurus concepts!",
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: [
        'guides/creating-pages',
        {
          type: 'category',
          label: 'Docs',
          link: {
            type: 'doc',
            id: 'guides/docs/introduction',
          },
          items: [
            'guides/docs/create-doc',
            {
              type: 'category',
              label: 'Sidebar',
              link: {
                type: 'doc',
                id: 'guides/docs/sidebar/index',
              },
              items: [
                'guides/docs/sidebar/items',
                'guides/docs/sidebar/autogenerated',
                'guides/docs/sidebar/multiple-sidebars',
              ],
            },
            'guides/docs/versioning',
            'guides/docs/multi-instance',
          ],
        },
        'blog',
        {
          type: 'category',
          label: 'Markdown Features',
          link: {
            type: 'doc',
            id: 'guides/markdown-features/introduction',
          },
          items: [
            'guides/markdown-features/react',
            'guides/markdown-features/tabs',
            'guides/markdown-features/code-blocks',
            'guides/markdown-features/admonitions',
            'guides/markdown-features/toc',
            'guides/markdown-features/assets',
            'guides/markdown-features/links',
            'guides/markdown-features/plugins',
            'guides/markdown-features/math-equations',
            'guides/markdown-features/diagrams',
            'guides/markdown-features/head-metadata',
          ],
        },
        'styling-layout',
        'swizzling',
        'static-assets',
        'search',
        'browser-support',
        'seo',
        'using-plugins',
        'deployment',
        {
          type: 'category',
          label: 'Internationalization',
          link: {type: 'doc', id: 'i18n/introduction'},
          items: [
            {
              type: 'doc',
              id: 'i18n/tutorial',
              label: 'Tutorial',
            },
            {
              type: 'doc',
              id: 'i18n/git',
              label: 'Using Git',
            },
            {
              type: 'doc',
              id: 'i18n/crowdin',
              label: 'Using Crowdin',
            },
          ],
        },
        'guides/whats-next',
      ],
    },
    {
      type: 'category',
      label: 'Advanced Guides',
      link: {type: 'doc', id: 'advanced/index'},
      items: [
        'advanced/architecture',
        'advanced/plugins',
        'advanced/routing',
        'advanced/ssg',
        'advanced/client',
      ],
    },
    {
      type: 'category',
      label: 'Upgrading',
      link: {
        type: 'doc',
        id: 'migration/index',
      },
      items: [
        'migration/v3',
        {
          type: 'category',
          label: 'To Docusaurus v2',
          items: [
            'migration/v2/migration-overview',
            'migration/v2/migration-automated',
            'migration/v2/migration-manual',
            'migration/v2/migration-versioned-sites',
            'migration/v2/migration-translated-sites',
          ],
        },
      ],
    },
  ],
  api: [
    'cli',
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};
export default sidebars;