侧边栏

侧边栏是文档的主要导航块。您可以在 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 可组合

返回与侧边栏相关的数据。返回的对象具有以下类型

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>