vite-plugin-vitepress-auto-sidebar

1.7.1 verified Mon Apr 27 auth: no javascript

Vite plugin that automatically generates VitePress sidebar configuration by scanning the docs directory structure. Version 1.7.1 supports options like ignoreList, collapsed groups, title extraction from markdown files or frontmatter, and auto-updates on file changes. Active development with frequent releases. Differentiates by being a dedicated Vite plugin rather than a build-time script, with live HMR support for sidebar regeneration.

Common errors

error [auto-sidebar] injected sidebar data successfully ↓

cause Plugin is working correctly; no error.

fix

No action needed.

error Cannot find module 'vite-plugin-vitepress-auto-sidebar' ↓

cause Package not installed or incorrect import path.

fix

Run npm install vite-plugin-vitepress-auto-sidebar and ensure import is correct.

error AutoSidebar is not a function ↓

cause Using named import instead of default import.

fix

Change import { AutoSidebar } to import AutoSidebar.

error TypeError: Cannot read properties of undefined (reading 'sidebar') ↓

cause VitePress config missing or sidebar property not cleared.

fix

Add themeConfig with empty sidebar or remove the sidebar property.

Warnings

breaking You must clear the existing sidebar object in your VitePress config or the plugin may not work properly. ↓

fix Remove the `sidebar` property from `themeConfig` in your config file.

gotcha The `ignoreIndexItem` option's default is `false`; if you have `index.md` files, they will appear as sidebar items unless set to `true`. ↓

fix Set `ignoreIndexItem: true` in plugin options.

deprecated The option `titleFromFileByYaml` may conflict with `titleFromFile`; if both true, frontmatter title takes precedence. ↓

fix Use only `titleFromFile` if you want markdown-level heading; use `titleFromFileByYaml` for frontmatter. They are not mutually exclusive.

gotcha If `path` does not exist, the plugin silently fails without error. Sidebar data will not be injected. ↓

fix Ensure the directory specified in `path` exists relative to project root.

gotcha File changes (add/delete .md) are watched only in dev mode; manual rebuild needed in production. ↓

fix Restart the dev server or trigger a production rebuild after file changes.

Install

npm install vite-plugin-vitepress-auto-sidebar

yarn add vite-plugin-vitepress-auto-sidebar

pnpm add vite-plugin-vitepress-auto-sidebar

Imports

AutoSidebar

wrong

const AutoSidebar = require('vite-plugin-vitepress-auto-sidebar')

correct

import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar'

ESM-only; CommonJS require will fail.

AutoSidebar (default import)

wrong

import { AutoSidebar } from 'vite-plugin-vitepress-auto-sidebar'

correct

import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar'

Package has a default export, not a named export.

options type

import type { AutoSidebarOptions } from 'vite-plugin-vitepress-auto-sidebar'

TypeScript users can import the options interface for type checking.

Quickstart

Configure the plugin in VitePress config to auto-generate sidebar from /docs structure.

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar'

export default defineConfig({
  vite: {
    plugins: [
      AutoSidebar({
        path: '/docs',
        ignoreList: ['public'],
        collapsed: false,
        ignoreIndexItem: true,
        titleFromFile: true,
        titleFromFileByYaml: true,
        scanRootMdFiles: true,
        deletePrefix: ''
      })
    ]
  },
  title: 'My Docs',
  description: 'Documentation site'
})