Generate Nested sidebar. Support Multiple Sidebar. Support TypeScript

Developed by Logic Spark team

:sunglasses: Video Demo

Basic Sidebar

https://github.com/logicspark/vitepress-plugin-nested-sidebar/assets/135820109/bf64884f-3aff-4d2b-81f8-4a3cb41b923b

Multiple Sidebar

https://github.com/logicspark/vitepress-plugin-nested-sidebar/assets/135820109/ca50fa7f-7ce7-48ec-ac70-562e2471dd8b

:building_construction: Built With

:rocket: Getting Started

Prerequisite

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

Installation

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

Other options

• yarn

  yarn add vitepress-plugin-nested-sidebar

• pnpm

  pnpm add vitepress-plugin-nested-sidebar

:fire: Usage

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

Import generateSidebar Function

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

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

Options of generateSidebar Function

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.

| Options | Type | Required | Description | | -------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sidebars | object|array | Yes | define sidebar menu name and link .md file in order to generate the headers use array for Basic sidebar use object for Multiple sidebar | | excludeFile | array | Optional | exclude file to not to generate in the sidebar menu | | includeIndexMd | boolean | Optional | generate the sidebar menu item from index.md |

Basic Sidebar

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

Multiple Sidebar

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

Utility Functions

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)

Importance of Layout.vue

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.

Import Utility Functions from Theme

Per Vitepress's Setup Wizard, there are three options

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

Option 1: Default 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.

:books: License

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

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

:pray: Acknowledgement

• Vitepress
• Img Shields