Basic Sidebar

Multiple Sidebar

The plugin is created with Vite + TypeScript. To start using this library, please make sure to install the following external libraries first:

• Node.js
• Vitepress

Support Node.js 18.12.0 (LTS) and above

There are a few ways you can install Plugin, namely npm, yarn and pnpm. If you install via npm, here is a single cmd to install this library

  npm install vitepress-plugin-nested-sidebar

• yarn

  yarn add vitepress-plugin-nested-sidebar

• pnpm

  pnpm add vitepress-plugin-nested-sidebar

You will need to import generateSidebar function and Layout.vue file. Without Layout.vue file, the lib may not work properly.

You will need to import function to generateSidebar menu under themeConfig setting of .vitpress/config.mts file:

import VitepressPluginNestedSidebar from "vitepress-plugin-nested-sidebar";

There is one required option, sidebars. The option supports both native basic and multiple sidebars which are native to Vitepress.

_Note: For more details of both types of sidebars, please check out Sidebar of Vitepress documentation.

[
  {
    text: string; /*optional*/ /*sidebar name*/
    link: string; /*optional*/ /*link to .md file*/
    collapsed: boolean; /*optional*/
  }
]

{
  ['file':string]:{
    text: string; /*optional*/
    link: string; /*optional*/
    collapsed: boolean; /*optional*/
  }
}

These 4 functions support the generateSidebar to work as intended:

calculateAndHighlightHeader - Check for scroll position with respect to the nearest header

calculateAndHighlightHeader(
header:{
  text,
  link,
  items,
},
options:{
  idName, /*optional /*in case of use another div to scroll*/
  adjustOffsetTop /*optional*/
})

checkMultipleSidebar - Check themeConfig sidebar if it is multiple or not

checkMultipleSidebar(sidebar:Object | Array)

resetHeader - Use to reset scroll position to the top

resetHeader();

filterSidebar - Filter the sidebar

filterSidebar(compare:string)

The utility functions need information from theme site and page which is retrieved from useData of the vitepress lib. And because the information can only be used within the .vue file, without the Layout.vue file, the utility functions may not work.

Per Vitepress's Setup Wizard, there are three options

1. Default Theme
2. Default Theme + Customization
3. Custom Theme

1. Create Layout.vue and index.ts files
2. Import the function into the Layout.vue file

import VitepressPluginNestedSidebar from "vitepress-plugin-nested-sidebar";

const { utility } = VitepressPluginNestedSidebar;

const {
  calculateAndHighlightHeader,
  resetHeader,
  filterSidebar,
  checkMultipleSidebar,
} = utility;

Note: You can also apply this instruction to Option 2 and Option 3. For the full sample in accordance with the live demo, please see our example directory.

Distributed under the MIT License. See LICENSE for more information.

Vitepress is licensed under MIT License. Click here for more information.

• Vitepress
• Img Shields