LV103-自动侧边栏配置详解

本文是自动侧边栏系列的第二篇，覆盖全部配置项：主题默认配置怎么读、navSidebarOption 三层结构里每个字段的作用、以及 frontmatter 级的逐文档定制。模式的原理请回看 LV100-自动侧边栏总览。

所有配置项的类型定义在 plugins/vitepress-auto-nav-sidebar/src/types.ts，共三层：NavSidebarOption（顶层）→ NavOption（导航栏）+ SidebarOption（侧边栏）。

一、配置入口与默认值

1. 配置写在哪里

mist 主题用户在 defineMistConfig 的 vitePlugins.navSidebarOption 里配置：

// docs/src/.vitepress/config.mts
defineMistConfig({
  useTheme: true,
  vitePlugins: {
    navSidebarOption: {
      path: "sdoc",
      navOption: { maxLevel: 2 },
      sideBarOption: { type: "object", collapsed: true },
    },
  },
});

2. 主题默认配置

不配置时，生效的是 packages/config/defaultConfig/vitePlugins.ts 里的默认值，逐项含义如下：

// packages/config/defaultConfig/vitePlugins.ts
navSidebarOption: {
  path: "sdoc",          // 扫描根目录：srcDir 下的 sdoc
  debugInfo: false,      // 关闭 config 阶段的调试输出
  navOption: {
    maxLevel: 2,         // 导航栏最多扫两层（一级 + 二级下拉）
    debugPrint: false,
    saveToFile: false,
  },
  sideBarOption: {
    type: "object",      // 侧边栏为对象形式（多侧边栏）
    ignoreList: ["index.md", "README.md"], // 忽略的文件/目录名
    initItems: false,    // 侧边栏 key 下直接挂文件树，不包一层分组
    collapsed: true,     // 分组默认折叠
    debugPrint: false,
    saveToFile: false,
  },
},

用户配置与默认值是浅合并（{ ...default, ...user }）：在 sideBarOption 里改一个字段，其余字段仍取默认值；但 navOption / sideBarOption 整个对象会以用户传入的为准整体覆盖默认——想只改一个字段时，记得把需要的默认字段一并写上。

3. initItems: false 的原因

默认配置里这行注释值得留意：设为 true 时进入某个导航栏路径可能不显示侧边栏。两种取值生成 structures 不同：

（1）initItems: true：sidebar["/sdoc/01-开发/"] = [{ text: "", items: [...文件树] }]，外面包一层分组项；

（2）initItems: false：sidebar["/sdoc/01-开发/"] = [...文件树]，直接是文件列表。

mist 主题的布局对第一种包裹形式支持不佳，因此默认关闭。

二、顶层配置 NavSidebarOption

path、debugInfo 加上两组子配置，共四个字段：

• path?: string：扫描根目录，相对 srcDir 解析（join(srcDir, path)）。默认不传时取 srcDir 本身；mist 默认 "sdoc"。它同时决定生成侧边栏 key 的第一段（/sdoc/...）与链接前缀；
• debugInfo?: boolean：config 钩子里打印 srcDir、baseDir、createRule、rewritesLength 四个中间变量，排查模式判定问题时打开；
• navOption?: NavOption：导航栏子配置，见第三节；
• sideBarOption?: SidebarOption：侧边栏子配置，见第四节。

三、导航栏配置 NavOption

配置项	类型	默认值	作用
maxLevel	number	1（ mist 默认 2）	最大扫描层级。一级目录是链接，二级目录收进下拉，超出层级的目录不再展开
ignoreList	(string | RegExp)[]	[]	忽略的文件/目录名，支持正则，追加在默认黑名单之后
path	string	-	单独指定导航栏扫描目录（一般由顶层 path 推导，无需手填）
debugPrint	boolean	false	打印最终生成的 nav 数据
saveToFile	boolean	false	把 nav 数据落到 .vitepress/cache/navigation-data.json

maxLevel 的语义在两种模式下略有差别：filePath 模式下层级由目录嵌套深度决定；rewrites 模式下到达 maxLevel 的目录必须有 index.md（链接取自 index.md 的 permalink），没有 index.md 的目录直接不显示。

四、侧边栏配置 SidebarOption

配置项较多，按功能分六组。

1. 扫描控制

• path?: string：侧边栏扫描目录（由顶层推导）；
• ignoreList?: Array<RegExp | string>：忽略的文件/目录名，支持正则。注意是追加到默认黑名单 ["node_modules", "dist", ".vitepress", "public"] 之后，默认黑名单无法移除；
• ignoreIndexMd?: boolean（默认 false）：忽略每个目录下的 index.md，不让目录页出现在侧边栏；
• scannerRootMd?: boolean（默认 true）：扫描根目录下的散装 md 文件，生成到 /sdoc/ 这个 key 下（根目录的 index.md 始终排除）。

2. 结构控制

• type?: "object" | "array"（默认 "object"）：object 是 Record<string, SidebarItem[]> 多侧边栏（按路径前缀切换）；array 是所有文档合成一个侧边栏；
• initItems?: boolean（默认 true，mist 默认 false）：见第一节说明；
• initItemsText?: boolean（默认 false）：initItems: true 时，包裹层的 text 是否填目录名（否则为空字符串）；
• rootTitle?: string（默认 "Root"）：type: "array" 且 scannerRootMd: true 时根目录分组的标题。

3. 外观

collapsed?: boolean | ((relativePath, text) => boolean)（默认 undefined）：分组是否默认折叠。传函数可按路径或标题精细控制，两个入参分别是当前项相对根目录的路径和侧边栏文本。

4. 标题

• titleFormMd?: boolean（默认 false）：是否把 md 文件的第一个一级标题纳入标题来源。开启后文件标题优先级为 frontmatter.title > md 一级标题 > 文件名；关闭时一级标题不参与。注意目录的标题取自 index.md 的逻辑也受它控制（见 LV106 第五节）；
• indexSeparator?: string：额外支持的序号分隔符。默认只认 01.标题.md 点分隔；设为 "_" 后 01_标题.md 也能解析出序号 01；
• prefixTransform? / suffixTransform?: (s) => string：对 frontmatter sidebarPrefix / sidebarSuffix 做二次加工，典型用法是把图标名包成 <i> 标签。

5. 排序

• sort?: boolean（默认 true）：开启 frontmatter sidebarSort 排序。开启时每个文件都要读 frontmatter，纯文件名序号排序的站点可以关掉省时间；
• defaultSortNum?: number（默认 9999）：没有 sidebarSort 时的排序值，即默认垫底；
• sortNumFromFileName?: boolean（默认 false）：用文件名序号替代 sidebarSort 参与排序。

6. 回调与调试

• sidebarResolved?：每个侧边栏（一个 key）生成完后的回调，可整体改写；
• sidebarItemsResolved?：每层 items 生成完后的回调；
• beforeCreateSidebarItems?：解析前的文件名数组过滤器，可剔除不想要的文件；
• ignoreWarn?: boolean（默认 false）：关闭序号出错、非 md 文件等警告；
• debugPrint / saveToFile：同导航栏，落盘路径为 .vitepress/cache/sidebar-data.json。

另有三个字段（resolveRule、checkRewritesPrefix、restart、localeRootDir）继承自 sidebar-resolve，在 auto-nav-sidebar 中未实现或不生效，详见 LV112-自动侧边栏的限制与避坑。

五、frontmatter 级配置

单篇文档的定制写在 md 文件的 frontmatter 里：

（1）sidebar: false：该文档不出现在侧边栏（导航栏不受影响）；

（2）sidebarSort: 10：排序权重，数值越小越靠前；未设置的文档取 defaultSortNum；

（3）sidebarPrefix / sidebarSuffix：标题前后缀，配合 prefixTransform 可实现图标：

---
sidebarPrefix: teek
---

配合 prefixTransform: p => \`` 后，侧边栏标题渲染出图标；

（4）title：frontmatter 标题，优先级高于文件名（titleFormMd: true 时还高于 md 一级标题）；

（5）permalink：永久链接，不直接作用于侧边栏外观，但决定 rewrites 模式下侧边栏链接的取值（见 LV109）。

六、常用配置示例

1. 换扫描目录

vitePlugins: {
  navSidebarOption: {
    path: "articles", // 从 src/articles 扫描
  },
},

2. 排除特定目录并开启 md 标题

vitePlugins: {
  navSidebarOption: {
    path: "sdoc",
    sideBarOption: {
      ignoreList: ["draft", /^__/], // 忽略 draft 目录和 __ 开头的文件
      titleFormMd: true,            // 文件标题可来自 md 一级标题
    },
  },
},

3. 调试侧边栏数据

vitePlugins: {
  navSidebarOption: {
    debugInfo: true, // 打印模式判定过程
    sideBarOption: { debugPrint: true, saveToFile: true },
  },
},

启动后控制台打印生成数据，同时 .vitepress/cache/sidebar-data.json 里有完整的最终数据，改配置前后对比这份文件即可确认效果。