侧边栏配置

侧边栏显示当前路由下的文档导航，帮助用户快速定位内容。

基础配置

简单侧边栏

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '入门指南',
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' },
          { text: '项目结构', link: '/guide/project-structure' }
        ]
      }
    ]
  }
})

多分组

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: '入门',
        items: [
          { text: '介绍', link: '/guide/' },
          { text: '安装', link: '/guide/installation' }
        ]
      },
      {
        text: '进阶',
        items: [
          { text: '主题定制', link: '/advanced/theme' },
          { text: '插件开发', link: '/advanced/plugins' }
        ]
      }
    ]
  }
})

多侧边栏

根据不同路径显示不同侧边栏：

export default defineConfig({
  themeConfig: {
    sidebar: {
      // /guide/ 路径下的侧边栏
      '/guide/': [
        {
          text: '入门指南',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' }
          ]
        }
      ],
      
      // /api/ 路径下的侧边栏
      '/api/': [
        {
          text: 'API 参考',
          items: [
            { text: '配置', link: '/api/config' },
            { text: '运行时', link: '/api/runtime' }
          ]
        }
      ]
    }
  }
})

可折叠分组

默认折叠

sidebar: [
  {
    text: '入门指南',
    collapsed: true,  // 默认折叠
    items: [
      { text: '介绍', link: '/guide/' },
      { text: '安装', link: '/guide/installation' }
    ]
  }
]

默认展开

sidebar: [
  {
    text: '入门指南',
    collapsed: false,  // 默认展开
    items: [
      { text: '介绍', link: '/guide/' }
    ]
  }
]

配置项详解

分组配置

interface SidebarItem {
  text?: string           // 分组标题
  items?: SidebarItem[]   // 子项
  link?: string           // 链接
  collapsed?: boolean     // 是否折叠
  base?: string           // 基础路径
  docFooterText?: string  // 文档页脚文字
}

链接项配置

sidebar: [
  {
    text: '指南',
    items: [
      {
        text: '介绍',
        link: '/guide/',
        // 可选：自定义活动状态匹配
        activeMatch: '/guide/'
      }
    ]
  }
]

基础路径

简化链接路径：

sidebar: [
  {
    text: '指南',
    base: '/guide/',  // 设置基础路径
    items: [
      { text: '介绍', link: '' },           // -> /guide/
      { text: '安装', link: 'installation' } // -> /guide/installation
    ]
  }
]

高级用法

嵌套分组

sidebar: [
  {
    text: '进阶',
    items: [
      {
        text: '主题',
        collapsed: true,
        items: [
          { text: '默认主题', link: '/theme/default' },
          { text: '自定义主题', link: '/theme/custom' }
        ]
      },
      {
        text: '组件',
        collapsed: true,
        items: [
          { text: '内置组件', link: '/components/built-in' },
          { text: '自定义组件', link: '/components/custom' }
        ]
      }
    ]
  }
]

动态生成

// 动态生成侧边栏
const guideSidebar = [
  'introduction',
  'installation',
  'project-structure',
  'first-page'
].map(slug => ({
  text: slug.replace(/-/g, ' ').replace(/^\w/, c => c.toUpperCase()),
  link: `/guide/${slug}`
}))

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          items: guideSidebar
        }
      ]
    }
  }
})

禁用侧边栏

全局禁用

export default defineConfig({
  themeConfig: {
    sidebar: false
  }
})

单页禁用

在页面的 Frontmatter 中：

---
sidebar: false
---

完整示例

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: '入门指南',
          base: '/guide/',
          items: [
            { text: '什么是 VitePress', link: 'what-is-vitepress' },
            { text: '安装与环境配置', link: 'installation' },
            { text: '项目结构解析', link: 'project-structure' },
            { text: '创建第一个页面', link: 'first-page' }
          ]
        }
      ],
      
      '/basics/': [
        {
          text: '基础功能',
          base: '/basics/',
          items: [
            { text: 'Markdown 扩展语法', link: 'markdown' },
            { text: 'Frontmatter 配置', link: 'frontmatter' },
            { text: '配置文件详解', link: 'configuration' },
            { text: '导航栏配置', link: 'navbar' },
            { text: '侧边栏配置', link: 'sidebar' }
          ]
        }
      ],
      
      '/theme/': [
        {
          text: '主题定制',
          base: '/theme/',
          items: [
            { text: '默认主题配置', link: 'default-theme' },
            { text: '自定义主题', link: 'custom-theme' },
            { text: 'CSS 变量覆盖', link: 'css-variables' },
            { text: '布局插槽', link: 'layout-slots' }
          ]
        }
      ],
      
      '/advanced/': [
        {
          text: '高级功能',
          base: '/advanced/',
          collapsed: false,
          items: [
            { text: '组件使用', link: 'components' },
            { text: '数据加载', link: 'data-loading' },
            { text: '多语言支持', link: 'i18n' },
            { text: '搜索功能', link: 'search' },
            { text: '部署与发布', link: 'deployment' }
          ]
        }
      ],
      
      '/best-practices/': [
        {
          text: '最佳实践',
          base: '/best-practices/',
          items: [
            { text: '性能优化', link: 'performance' },
            { text: '常见问题', link: 'faq' },
            { text: '插件扩展', link: 'plugins' }
          ]
        }
      ]
    }
  }
})

下一步

接下来学习 默认主题配置 来定制站点外观。