側邊欄

側邊欄是文件的主要導覽區塊。您可以在 themeConfig.sidebar 中設定側邊欄選單。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
          ...
        ]
      }
    ]
  }
}

基礎

側邊欄選單最簡單的形式是傳入單一連結陣列。第一層項目定義側邊欄的「區段」。它應該包含 text（區段標題）和 items（實際導覽連結）。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          ...
        ]
      },
      {
        text: 'Section Title B',
        items: [
          { text: 'Item C', link: '/item-c' },
          { text: 'Item D', link: '/item-d' },
          ...
        ]
      }
    ]
  }
}

每個 link 應該指定實際檔案的路徑，從 / 開始。如果您在連結尾端加上斜線，它會顯示對應目錄的 index.md。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          // This shows `/guide/index.md` page.
          { text: 'Introduction', link: '/guide/' }
        ]
      }
    ]
  }
}

您可以進一步巢狀側邊欄項目，從根層開始計算，最多可達 6 層。請注意，超過 6 層的巢狀項目會被忽略，不會顯示在側邊欄中。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Level 1',
        items: [
          {
            text: 'Level 2',
            items: [
              {
                text: 'Level 3',
                items: [
                  ...
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

多個側邊欄

您可以根據頁面路徑顯示不同的側邊欄。例如，如本網站所示，您可能想在文件中建立獨立的內容區段，例如「指南」頁面和「設定」頁面。

為此，請先將您的頁面整理到每個所需區段的目錄中

.
├─ guide/
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md

然後，更新您的設定以定義每個區段的側邊欄。這次，您應該傳遞物件，而不是陣列。

export default {
  themeConfig: {
    sidebar: {
      // This sidebar gets displayed when a user
      // is on `guide` directory.
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Index', link: '/guide/' },
            { text: 'One', link: '/guide/one' },
            { text: 'Two', link: '/guide/two' }
          ]
        }
      ],

      // This sidebar gets displayed when a user
      // is on `config` directory.
      '/config/': [
        {
          text: 'Config',
          items: [
            { text: 'Index', link: '/config/' },
            { text: 'Three', link: '/config/three' },
            { text: 'Four', link: '/config/four' }
          ]
        }
      ]
    }
  }
}

可摺疊側邊欄群組

透過將 collapsed 選項新增到側邊欄群組，它會顯示一個切換按鈕來隱藏/顯示每個區段。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        collapsed: false,
        items: [...]
      }
    ]
  }
}

預設所有區段都是「開啟」的。如果你希望它們在初始頁面載入時為「關閉」，請將 collapsed 選項設定為 true。

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        collapsed: true,
        items: [...]
      }
    ]
  }
}

useSidebar composable

傳回側邊欄相關資料。傳回的物件具有以下類型

export interface DocSidebar {
  isOpen: Ref<boolean>
  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
  hasSidebar: ComputedRef<boolean>
  hasAside: ComputedRef<boolean>
  leftAside: ComputedRef<boolean>
  isSidebarEnabled: ComputedRef<boolean>
  open: () => void
  close: () => void
  toggle: () => void
}

範例

<script setup>
import { useSidebar } from 'vitepress/theme'

const { hasSidebar } = useSidebar()
</script>

<template>
  <div v-if="hasSidebar">Only show when sidebar exists</div>
</template>