Star on GitHub Create Issues Buy me a Bubble Tea

Sidebar

About 1269 wordsAbout 4 min

GuideQuick Start

2025-10-08

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 Docs

basic.md

types.md

rust# Rust Docs

tuple.md

struct.md

README.md# Site Homepage

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 Docs',
        sidebar
: ['basic', 'types'],
      },
      {
        type
: 'doc',
        dir
: 'rust',
        linkPrefix
: '/rust/',
        title
: 'Rust Docs',
        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 Docs',
      sidebar
: ['basic', 'types'],
    },
    {
      type
: 'doc',
      dir
: 'rust',
      linkPrefix
: '/rust/',
      title
: 'Rust Docs',
      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 Docs',
  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 Docs',
  sidebar: [
    'guide/intro.md',
    'guide/getting-start.md',
    'config/config-file.md',
  ]
})

File Structure Example

Assume the TypeScript Docs 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

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

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' },
  ],
})

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/13/26, 3:56 PM

View All Changelog

e4dae-docs: improve docs (#1071)on 10/13/26
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

Collection

markdown

code block

code repl

charts

resource embedded

Custom Homepage

Sidebar

Overview

File Structure and Basic Configuration

Directory Structure Design

Configuration via `sidebar`

Configuration via `collection` Recommended

Advanced Configuration Management

Modular Configuration Solution

Large Project Configuration Splitting

Sidebar Configuration Details

File Structure Example

Auto-generated Sidebar

Auto-generated Sub-sidebar

Custom Sidebar Configuration

Basic Configuration Types

Configuration Examples

Prefix Path Processing Rules

Visual Enhancement Features

Icon Configuration

Badge Feature v1.0.0-rc.143 +

Group Separators

Contributors

Changelog