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

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:

---
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/9/25, 7:46 AM

View All Changelog

• 38505-docs: update en docs (#708)on 10/9/25