⚡ VitePress Plugin: Auto Sidebar

Generate the VitePress sidebar through the folder structure.

• ✨  Release Notes
• 🎮  Live Playground

Features

• 🚀 Automatic sidebar generation from folder structure
• 📁 Support for nested directories
• 🎨 Customizable directory titles
• 📝 Frontmatter title support
• 🔄 Collapsible sidebar sections
• 📦 Small library with minimal dependencies (only gray-matter for frontmatter parsing)
• 🔒 Full TypeScript support with type definitions
• ⚡ Fast and efficient file system operations
• 🛡️ Built-in error handling and validation

Setup

pnpm add vitepress-plugin-auto-sidebar # pnpm (recommended)
npm i vitepress-plugin-auto-sidebar # npm
yarn add vitepress-plugin-auto-sidebar # yarn

Basic usage

.vitepress/config.js

import { getSidebar } from 'vitepress-plugin-auto-sidebar'

export default {
  themeConfig: {
    sidebar: getSidebar({ contentRoot: '/', contentDirs: ['team'], collapsible: true, collapsed: true })
  }
}

Options

Option	Type	Default	Description
contentRoot	string	'/'	Root directory of your VitePress documentation (relative to project root)
contentDirs	(string | ContentDir)[]	['/']	Array of directories to index within contentRoot. Can be simple strings or objects with { path: string, title?: string } for custom titles
collapsible	boolean	true	Whether sidebar groups can be collapsed/expanded
collapsed	boolean	true	Whether sidebar groups are initially collapsed on page load
useFrontmatter	boolean	false	Whether to use frontmatter titles from markdown files instead of filename-based titles

Advanced Usage

Custom Directory Titles

import { getSidebar } from 'vitepress-plugin-auto-sidebar'

export default {
  themeConfig: {
    sidebar: getSidebar({
      contentRoot: '/docs',
      contentDirs: [
        'getting-started',
        { path: 'api', title: 'API Reference' },
        { path: 'guides', title: '📚 User Guides' }
      ]
    })
  }
}

Using Frontmatter Titles

Add frontmatter to your markdown files:

---
title: My Custom Page Title
---

# My Custom Page Title

Your content here...

Then enable frontmatter support:

import { getSidebar } from 'vitepress-plugin-auto-sidebar'

export default {
  themeConfig: {
    sidebar: getSidebar({
      contentRoot: '/',
      contentDirs: ['docs'],
      useFrontmatter: true
    })
  }
}

Tips & Best Practices

• Ignore Files: Prefix any .md file with an underscore (_example.md) to exclude it from the sidebar
• Organize Structure: Use clear, descriptive folder names - they become sidebar section titles
• File Naming: Use kebab-case for files (my-page.md) - they're automatically converted to "My Page"
• Nested Directories: The plugin recursively scans all subdirectories for a complete sidebar structure
• Empty Directories: Directories without any valid .md files are automatically excluded from the sidebar

Development

Setup

# Clone the repository
git clone https://github.com/JonathanSchndr/vitepress-plugin-auto-sidebar.git
cd vitepress-plugin-auto-sidebar

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the package
pnpm run build

Available Scripts

• pnpm run build - Build the package for production
• pnpm run typecheck - Run TypeScript type checking
• pnpm run lint - Lint code with Oxlint
• pnpm run lint:fix - Auto-fix linting issues
• pnpm run format - Format code with Prettier
• pnpm run format:check - Check code formatting
• pnpm test - Run tests
• pnpm run test:watch - Run tests in watch mode
• pnpm run test:ui - Run tests with UI
• pnpm run test:coverage - Run tests with coverage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Follow the existing code style (Oxlint + Prettier)
2. Add tests for new features
3. Update documentation as needed
4. Use semantic commit messages (conventional commits)

License

Copyright (c) 2025 Jonathan Schneider MIT License