VitePress Sidebar 可通过两个函数自动生成侧边栏：withSidebar 和 generateSidebar。通常建议使用 withSidebar，它支持热重载，也是标准做法

详细配置可查看：https://vitepress-sidebar.cdget.com/

一：使用 generateSidebar 函数

bash

import { defineConfig } from 'vitepress'
import { generateSidebar } from 'vitepress-sidebar';

sidebar: generateSidebar({
     ============ [ 路径解析 ] ============
     documentRootPath: '/',  # 文档根目录路径
     scanStartPath: null,  # 扫描起始目录，为空则扫描整个 documentRootPath
     resolvePath: null,  # 生成链接的前缀路径，用于多侧边栏匹配
     basePath: null,  # 基础路径，影响最终生成的 url
     followSymlinks: false,  # 是否跟随符号链接（软链接）扫描文件
    
     ============ [ 分组折叠 ] ============
     collapsed: false,  # 侧边栏分组是否默认折叠
     collapseDepth: 2,  # 自动折叠的深度层级
     collapseFromLevel: 1,  # 从第几级开始折叠
     rootGroupText: 'Contents',  # 根分组的显示文字
     rootGroupLink: 'https:github.com/jooy2',  # 根分组的链接地址
     rootGroupCollapsed: false,  # 根分组是否默认折叠
    
     ============ [ 获取菜单标题 ] ============
     useTitleFromFileHeading: false,  # 从文件中的 '#' 标题提取侧边栏文字
     useTitleFromFrontmatter: false,  # 从 frontmatter 的 'title' 字段提取
     useFolderLinkFromIndexFile: false,  # 文件夹链接指向其 index.md
     useFolderTitleFromIndexFile: false,  # 文件夹标题从其 index.md 的标题获取
     frontmatterTitleFieldName: 'title',  # frontmatter 中用于标题的字段名
    
     ============ [ 获取菜单链接 ] ============
     useFolderLinkFromSameNameSubFile: false,  # 文件夹链接指向与其同名的子文件
     useFolderLinkFromIndexFile: false,  # 文件夹链接指向  index.md
     folderLinkNotIncludesFileName: false,  # 文件夹链接不包含文件名（只到文件夹路径）
    
     ============ [ 包含 / 排除 ] ============
     excludeByGlobPattern: ['README.md', 'folder/'],  # 按 Glob 模式排除文件/文件夹，如  ['README.md', 'folder/']
     excludeFilesByFrontmatterFieldName: 'exclude',  # 根据 frontmatter 某字段排除文件
     excludeByFolderDepth: undefined,  # 排除超过指定深度的文件夹
     includeDotFiles: false,  # 是否包含以 '.' 开头的隐藏文件
     includeEmptyFolder: false,  # 是否包含空文件夹
     includeRootIndexFile: false,  # 是否包含根目录的 index.md
     includeFolderIndexFile: false,  # 是否在侧边栏显示文件夹的 index.md
    
     ============ [ 标题样式 ] ============
     hyphenToSpace: false,  # 将文件名中的 '-' 替换为空格
     underscoreToSpace: false,  # 将文件名中的 '_' 替换为空格
     capitalizeFirst: false,  # 首字母大写
     capitalizeEachWords: false,  # 每个单词首字母大写
     keepMarkdownSyntaxFromTitle: false,  # 保留标题中的 Markdown 语法
     removePrefixAfterOrdering: false,  # 排序前缀（如  01. ）在显示时移除
     prefixSeparator: '.',  # 排序前缀的分隔符 
    
     ============ [ 排序 ] ============
     manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],  # 手动指定文件排序优先级，如  ['first.md', 'second']
     sortFolderTo: null,  # 文件夹排序位置：'top' 置顶 / 'bottom' 置底
     sortMenusByName: false,  # 按文件名排序
     sortMenusByFileDatePrefix: false,  # 按文件名中的日期前缀排序
     sortMenusByFrontmatterOrder: false,  # 按 frontmatter 的 'order' 字段排序
     frontmatterOrderDefaultValue: 0,  # 'order' 字段的默认值
     sortMenusByFileCreateDate: false,  # 按文件创建时间排序
     sortMenusByFileModifyDate: false,  # 按文件修改时间排序
     sortMenusByFrontmatterDate: false,  # 按 frontmatter 的 'date' 字段排序
     sortMenusOrderByDescending: false,  # 降序排列（默认升序）
     sortMenusOrderNumericallyFromTitle: false,  # 从标题中提取数字排序
     sortMenusOrderNumericallyFromLink: false,  # 从链接中提取数字排序
    
     ============ [ 调试 ] ============
     debugPrint: false,  # 调试模式，打印生成的侧边栏结构到控制台
  })

二：使用 withSidebar 函数

bash

// `.vitepress/config.js`
import { defineConfig } from 'vitepress'
import { withSidebar } from 'vitepress-sidebar';

const vitePressOptions = {
  // VitePress's options here...
  title: 'VitePress Sidebar',
  themeConfig: {
    // ...
  }
};

const vitePressSidebarOptions = {
  // VitePress Sidebar's options here...
  documentRootPath: '/',
  collapsed: false,
  capitalizeFirst: true
};

export default defineConfig(withSidebar(vitePressOptions, vitePressSidebarOptions));

多侧边栏操作方法

多侧边栏是一项允许根据特定 URI 路径显示不同侧边栏菜单的功能。只需在 vitepress-sidebar 中进行一些简单设置，就能轻松实现这一功能。最终，VitePress将按照预期输出选项。要先了解有关多侧边栏的更多信息，建议查看下面VitePress 的官方文档：

https://vitepress.dev/zh/reference/default-theme-sidebar#multiple-sidebars

基本用法

首先，假设有一个名为 docs 的根项目，其中有名为 guide 和 config 的子目录，如：

bash

docs/
├─ guide/
│  ├─ index.md
│  ├─ one.md
│  ├─ two.md
│  └─ do-not-include.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md

当URL位于 /guide页面时，用户希望菜单仅显示 guide 的子菜单，隐藏 config 的子菜单。同样，当 guide 位于 /config 页面时，希望隐藏 guide 的子菜单。

要在 vitepress-sidebar 中实现此功能，需要采用与现有设置不同的方法。

像以前一样使用 withSidebar 函数，但传递一个数组。该数组至少包含一个来自vitepress-sidebar的选项。数组中的值可以是任意数量的URL，当然也可以使用不同的设置进行配置。

bash

// 必须传递数组参数!!!!
const vitePressConfigs = {
  /* ... */
};

export default defineConfig(
  withSidebar(vitePressConfigs，[
    {
      documentRootPath: 'docs',
      scanStartPath: 'guide',
      basePath: '/guide/',
      resolvePath: '/guide/',
      useTitleFromFileHeading: true
    },
    {
      documentRootPath: 'docs',
      scanStartPath: 'config',
      resolvePath: '/config/',
      useTitleFromFrontmatter: true
    }
  ])
);

这些选项的值在结果中的使用情况如下：

bash

{
  <resolvePath>: [
    {
      base: <basePath or resolvePath>,
      items: [...] // `<scanStartPath>/path/to/items`
    }
  ]
}

下面是上述设置的输出示例：

bash

{
  '/guide/': {
    base: '/guide/',
    items: [
      {
        text: 'One',
        link: 'one'
      },
      {
        text: 'Two',
        link: 'two'
      }
    ]
  },
  '/config/': {
    base: '/config/',
    items: [
      {
        text: 'Three',
        link: 'three'
      },
      {
        text: 'Four',
        link: 'four'
      }
    ]
  }
}

多个侧边栏选项

以下选项可用于多个侧边栏:scanStartPath、basePath和resolvePath。每个选项都是可选的,但应根据具体情况正确使用。

下文将对每个选项进行说明，但建议首先参考选项页面上对每个选项的描述，以下描述基于以下示例：

bash

docs/
├─ .vitepress/
├─ guide/
│  ├─ api/
│  │  ├─ api-one.md
│  │  └─ api-two.md
│  ├─ one.md
│  └─ two.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md

scanStartPath

此选项用于为不同的路由规则指定不同的根目录。documentRootPath 是实际要扫描的根目录(即.vitepress目录所在的位置)，而 scanStartPath 是此路由规则中实际要显示的根目录。

例如，若要仅包含 /guide 目录中的文件，请将 scanStartPath 的值指定为 guide。但是，documentRootPath 中的路径不应包含在内。

resolvePath

VitePress使用此选项在遇到特定URI时显示相关菜单。例如，如果想在到达 example.com/guide/api 时仅显示 guide/api 目录的内容，则 resolvePath 的值为 /guide/api。建议在路径前添加/。

通常，它的值与 scanStartPath 类似，但有时可能需要为 i18n 路由指定不同的值。

basePath

此选项主要用于VitePress的重写规则，否则为可选。

它取代了VitePress中base路径的值。如果未指定该值,则指定resolvePath的值或根路径(/)。

如果目录的实际路径与URI中的路径结构不同,您应该能够通过重写功能导航到页面。通常情况下,侧边栏会根据根目录生成路径,而不会引用VitePress中的重写路径。

例如,假设您有一个重写规则,如下所示:

const vitePressConfigs = {
  rewrites: {
    'guide/:page': 'help/:page'
  }
};

const vitePressSidebarConfigs = [
  {
    documentRootPath: 'docs',
    scanStartPath: 'guide',
    resolvePath: '/guide/'
  }
];

export default defineConfig(withSidebar(vitePressConfigs，vitePressSidebarConfigs));

guide/one.md 文档显示在 help/one 的路径中。但如果这样做，侧边栏将不会显示菜单，因为它会尝试找到 help/one,而这是路径本身。

要解决这个问题,请将 basePath 中的路径改为 help:

const vitePressConfigs = {
  rewrites: {
    'guide/:page': 'help/:page'
  }
};

const vitePressSidebarConfigs = [
  {
    documentRootPath: 'docs',
    scanStartPath: 'guide',
    basePath: 'help'，// <---------------------- 添加这一行
    resolvePath: '/guide/'
  }
];

export default defineConfig(withSidebar(vitePressConfigs，vitePressSidebarConfigs));

显示带有复杂路径和 URI 的菜单

上面的例子通常是在路径按步骤定义的情况下，但当我们想显示按步骤深入的文件夹时，特别是当 URI 较短或使用与实际文件夹路径不同的约定时，需要使用额外的方法。例如，有一个这样的文件夹结构：

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

这次，我们希望当到达单级 URI /api 时，在 docs/guide/api 中显示菜单。预期的菜单仅显示 api-one.md 和 api-two.md。

withSidebar([
  {
    documentRootPath: 'docs',
    scanStartPath: 'guide/api',
    resolvePath: '/api/'
  }
]);

但是，如果这样配置选项，将无法显示菜单，因为 api 目录是 guide 的子目录。VitePress无法检测到这一点，并会导航到一个不存在的文档。

要解决这个问题,需要同时使用VitePress的路由功能，请参阅以下文章以获取说明: https://vitepress.dev/zh/guide/routing#route-rewrites

按照上面的示例，在 defineConfig 中的 VitePress 设置中添加 rewrites 选项:

const vitePressConfigs = {
  /* [START] Add This */
  rewrites: {
    'guide/api/:page': 'api/:page'
  }
  /* [END] Add This */
};

const vitePressSidebarConfigs = {
  documentRootPath: 'docs',
  scanStartPath: 'guide/api',
  resolvePath: '/api/'
};

export default defineConfig(withSidebar(vitePressConfigs，vitePressSidebarConfigs));

现在，当 URI 路径以 /api 开头时，将显示 docs/guide/api 的子菜单！

一：使用 generateSidebar 函数 ​

二：使用 withSidebar 函数 ​

多侧边栏操作方法 ​

基本用法 ​

多个侧边栏选项 ​

scanStartPath ​

resolvePath ​

basePath ​

显示带有复杂路径和 URI 的菜单 ​

一：使用 generateSidebar 函数

二：使用 withSidebar 函数

多侧边栏操作方法

基本用法

多个侧边栏选项

scanStartPath

resolvePath

basePath

显示带有复杂路径和 URI 的菜单