Getting Started

This guide will help you install and configure VitePress Plugin Sidebar Toggle for your documentation site.

Prerequisites

Before installing VitePress Plugin Sidebar Toggle, you need to have:

• A VitePress project set up
• Node.js and npm/yarn/pnpm/bun installed

If you don't have a VitePress project yet, follow the VitePress installation guide to create one.

Installation

1. Install the plugin using your preferred package manager:

npm

npm install vitepress-plugin-sidebar-toggle

yarn

yarn add vitepress-plugin-sidebar-toggle

pnpm

pnpm add vitepress-plugin-sidebar-toggle

bun

bun add vitepress-plugin-sidebar-toggle

Basic Configuration

2. Add the plugin to your VitePress theme configuration file:

.vitepress/theme/index.js

import DefaultTheme from 'vitepress/theme'
import { useSidebarToggle } from 'vitepress-plugin-sidebar-toggle'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    useSidebarToggle()
  },
}

.vitepress/theme/index.ts

import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { useSidebarToggle } from 'vitepress-plugin-sidebar-toggle'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    useSidebarToggle()
  },
} satisfies Theme

SSR Configuration

3. To ensure the plugin works correctly with server-side rendering (SSR), you need to configure Vite to not externalize the plugin during SSR. Add the following configuration to your .vitepress/config.js or .vitepress/config.ts file:

export default defineConfig({
    vite: {
        ssr: {
            noExternal: [
                'vitepress-plugin-sidebar-toggle', 
            ],
        },
    },
    // other configurations...
})

That's it! Your VitePress site now has a sidebar toggle button that allows users to hide or show the sidebar.

How It Works

The plugin adds a toggle button to your VitePress site that allows users to hide or show the sidebar. When the sidebar is hidden, the content area expands to use the full width of the page.

The plugin also remembers the user's preference using localStorage, so the sidebar state will be preserved when the user navigates between pages or returns to the site later.

Customization

The plugin uses CSS variables from your VitePress theme for styling, so it should blend in with your site's design automatically. If you want to customize the appearance of the toggle button, you can override the CSS variables in your own stylesheet.

Next Steps

Now that you have installed and configured VitePress Plugin Sidebar Toggle, you can:

• Check out the Example page to see the plugin in action
• Explore other VitePress plugins and themes to enhance your documentation site