Overview

Sidebar is a common page navigation method in documentation, enabling quick positioning to document content.

The theme provides two ways to configure the sidebar:

• Configure sidebar through the sidebar option in theme configuration
• Configure sidebar in collections of type doc

This page is the main document for sidebars

This is the complete guide to sidebars, covering directory structure, basic configuration, advanced usage, configuration details and visual enhancements.

If you only want to quickly compare the syntax of the two configuration entry points, see Sidebar Configuration (reference).

File Structure and Basic Configuration

Directory Structure Design

A typical project structure might look like:

docs

typescript# TypeScript Study Notes

basic.md

types.md

rust# Rust Programming Notes

tuple.md

struct.md

README.md# Site Homepage

Configuration via sidebar

This approach is suitable for simple and compact documentation sites.

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
sidebar
: {
      '/typescript/': [
        'basic',
        'types'
      ],
      '/rust/': [
        'tuple',
        'struct'
      ]
    }
  })
})

.vuepress/plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'

export default 
defineThemeConfig
({
  
sidebar
: {
    '/typescript/': [
      'basic',
      'types'
    ],
    '/rust/': [
      'tuple',
      'struct'
    ]
  }
})

Configuration via collection Recommended

collections can flexibly organize and manage different categories of documents within a site. This approach is suitable for complex sites.

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
collections
: [
      {
        
type
: 'doc',
        
dir
: 'typescript',
        
linkPrefix
: '/typescript/',
        
title
: 'TypeScript Notes',
        
sidebar
: ['basic', 'types'],
      },
      {
        
type
: 'doc',
        
dir
: 'rust',
        
linkPrefix
: '/rust/',
        
title
: 'Rust Notes',
        
sidebar
: ['tuple', 'struct'],
      }
    ],
  })
})

.vuepress/plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'

export default 
defineThemeConfig
({
  
collections
: [
    {
      
type
: 'doc',
      
dir
: 'typescript',
      
linkPrefix
: '/typescript/',
      
title
: 'TypeScript Notes',
      
sidebar
: ['basic', 'types'],
    },
    {
      
type
: 'doc',
      
dir
: 'rust',
      
linkPrefix
: '/rust/',
      
title
: 'Rust Notes',
      
sidebar
: ['tuple', 'struct'],
    }
  ],
})

Configuration Timing Recommendation

Complete the collection configuration before creating document files. The theme's auto-frontmatter feature will automatically generate permanent links and sidebar structures based on the configuration.

Advanced Configuration Management

Modular Configuration Solution

For complex projects, it's recommended to use the type-safe configuration tools provided by the theme:

.vuepress/collections.ts

import { 
defineCollection
, 
defineCollections
 } from 'vuepress-theme-plume'

// Single collection configuration
const 
typescript
 = 
defineCollection
({
  
type
: 'doc',
  
dir
: 'typescript',
  
title
: 'TypeScript Notes',
  
linkPrefix
: '/typescript/',
  
sidebar
: [
    'guide/intro.md',
    'guide/getting-start.md',
    'config/config-file.md',
  ]
})

// Export all collection configurations
export default 
defineCollections
([
  
typescript

])

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'
import 
collections
 from './collections'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
collections

  }),
})

Large Project Configuration Splitting

When dealing with numerous collections, a modular configuration structure can be adopted:

docs

.vuepress

collections

typescript.ts

rust.ts

index.ts

…

typescript

…

rust

…

Configuration code organization example:

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'
import 
collections
 from './collections/index.ts'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
collections

  }),
})

.vuepress/collections/index.ts

import { 
defineCollections
 } from 'vuepress-theme-plume'
import 
rust
 from './rust'
import 
typescript
 from './typescript'

export default 
defineCollections
([
  
rust
,
  
typescript
,
])

.vuepress/collections/typescript.ts

import { defineCollection } from 'vuepress-theme-plume'

export default defineCollection({
  type: 'doc',
  dir: 'typescript',
  link: '/typescript/',
  title: 'TypeScript Notes',
  sidebar: [
    'guide/intro.md',
    'guide/getting-start.md',
    'config/config-file.md',
  ]
})

Sidebar Configuration Details

File Structure Example

Assume the TypeScript Notes contain the following structure:

docs

typescript

guide

intro.md

getting-start.md

config

config-file.md

configuration.md

reference

basic.md

syntax.md

modules.md

built-in

types

Required.md

Omit.md

README.md

Auto-generated Sidebar

The simplest configuration uses auto-generation:

import { defineCollection } from 'vuepress-theme-plume'

export default defineCollection({
  type: 'doc',
  dir: 'typescript',
  sidebar: 'auto' // Auto-generate sidebar
})

The theme automatically configures the sidebar based on the directory structure.

Sorting Control: Manage display order through numeric prefixes

typescript

1.guide

1.intro.md

2.getting-start.md

2.config

1.config-file.md

2.configuration.md

…

Numeric prefixes are used only for sorting and are not displayed in the sidebar.

Auto-collapse: By default, the sidebar does not auto-collapse. You can enable auto-collapse by configuring sidebarCollapsed:

import { defineCollection } from 'vuepress-theme-plume'

export default defineCollection({
  type: 'doc',
  dir: 'typescript',
  sidebar: 'auto',
  sidebarCollapsed: true, 
})

sidebarCollapsed has the following optional values:

• undefined: Default, no auto-collapse
• true: Default all collapsed
• false: Default all expanded

Auto-generated Sub-sidebar

For more flexible sidebar control and reduced configuration complexity, the theme allows configuring only auto-generated sub-sidebars:

import { defineCollection } from 'vuepress-theme-plume'

export default defineCollection({
  type: 'doc',
  dir: 'typescript',
  sidebar: [
    // Sub-items automatically read the typescript/guide directory
    { text: 'Guide', prefix: 'guide', items: 'auto' },
    // Sub-items automatically read the typescript/config directory
    { text: 'Configuration', prefix: 'config', items: 'auto' },
  ],
})

Custom Sidebar Configuration

Basic Configuration Types

interface SidebarItem {
  text?: string // Display text
  link?: string // Link address
  icon?: ThemeIcon // Icon configuration
  badge?: string | ThemeBadge // Badge
  prefix?: string // Link prefix
  items?: 'auto' | (string | SidebarItem)[] // Next level sidebar
  collapsed?: boolean // Collapse state
}

Configuration Examples

Basic Link Configuration:

Using shorthand form, you can pass markdown file paths or page link addresses. The theme automatically reads the file's frontmatter configuration for sidebar settings.

sidebar: [
  // For absolute paths:
  // In themeConfig.sidebar, paths are relative to the `key` prefix
  // In collections, paths are relative to `dir`
  '/guide/intro.md', // Markdown file path
  '/guide/getting-start/', // Page link address
  '/config/config-file', // Can omit `.md` extension
]

Complete Object Configuration:

sidebar: [
  { text: 'Introduction', link: '/guide/intro' },
  { text: 'Quick Start', link: '/guide/getting-start' },
]

Nested Group Configuration:

sidebar: [
  {
    text: 'Guide',
    prefix: '/guide',
    items: [
      { text: 'Introduction', link: 'intro' },
      'getting-start', // Shorthand form
    ],
  },
  {
    text: 'Configuration',
    prefix: '/config',
    items: 'auto', // Auto-generate sidebar for this group
  },
]

Prefix Path Processing Rules

prefix is used to simplify link configurations with the same prefix:

const sidebarItem: SidebarItem = {
  prefix: '/guide',
  items: [
    'intro', // → /guide/intro.md
    '/config/config-file', // → /config/config-file.md (absolute path)
    { link: '/blog/' }, // → /guide/blog/
    { link: '/config/' } // → /config.md (absolute path)
  ]
}

Path Judgment Rules:

• Starts with /: Absolute path, does not concatenate prefix
• Other cases: Relative path, concatenated with prefix

Multi-level Nesting Example:

const sidebarItem: SidebarItem = {
  prefix: '/guide',
  items: [
    'intro', // → /guide/intro.md
    {
      prefix: '/config', // Absolute path, discards parent prefix
      items: ['config-file'] // → /config/config-file.md
    },
    {
      prefix: 'blog', // Relative path, concatenates with parent prefix
      items: ['intro'] // → /guide/blog/intro.md
    }
  ]
}

Depth Limitation

Avoid sidebar configurations with more than 3 levels of nesting, as excessive depth affects user experience and interface aesthetics.

Visual Enhancement Features

Icon Configuration

Supports multiple icon sources, configured via markdown.icon.provide:

sidebar: [
  {
    text: 'Guide',
    prefix: '/guide',
    icon: 'ep:guide', // Iconify icon
    items: [
      { text: 'Introduction', link: 'intro', icon: 'ph:info-light' },
    ],
  },
]

Local Icon Configuration:

const sidebarItem: SidebarItem = {
  text: 'Guide',
  icon: '/images/guide.png', // Local image
  items: [
    {
      text: 'Introduction',
      icon: 'https://example.com/icon.png' // Remote image
    },
  ]
}

Local Resource Paths

Local image paths should start with / and correspond to the .vuepress/public/ directory:

docs

.vuepress

public

images

guide.png

info.png

Badge Feature v1.0.0-rc.143 +

Provide additional information hints through badges:

sidebar: [
  {
    text: 'Guide',
    badge: { text: 'New', type: 'danger' }, // Object form
    items: [
      { text: 'Introduction', badge: 'Recommended' }, // String shorthand
    ],
  },
]

Frontmatter Configuration:

frontmatter

---
title: Introduction
badge:
  text: New Feature
  type: danger
---

Group Separators

Add visual separation in complex sidebars:

sidebar: [
  {
    text: 'Guide',
    items: [
      'Item 1',
      'Item 2',
      { text: 'Advanced Features', link: '---' }, // Separator
      'Item 3',
      'Item 4',
    ],
  },
]

Separator Characteristic: The link field contains at least three consecutive - characters

Contributors

pengzhanbo

Changelog

10/11/26, 4:27 AM

View All Changelog

• 60619-docs: improve docs (#1069)on 10/11/26
• 0daf2-docs: improve docs (#929)on 7/15/26
• 39a76-feat(plugin-md-power)!: use # as the comment delimiter (#870)on 4/2/26
• 38505-docs: update en docs (#708)on 10/9/25

Edit this page

Previous pageProject Structure

Next pagefrontmatter