Skip to content

Latest commit

 

History

History
217 lines (149 loc) · 7.15 KB

README.md

File metadata and controls

217 lines (149 loc) · 7.15 KB
Raw

🔌 Vitepress Plugin - Nested Sidebar

Generate Nested sidebar. Support Multiple Sidebar. Support TypeScript

Developed by Logic Spark team

npm Typescript MIT License



😎 Video Demo

Basic Sidebar

Demo-Basic.mov

Multiple Sidebar

Demo-Multiple-sidebar.mov

🏗️ Built With

  1. Typescript
  2. Vite

🚀 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:

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

🔥 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.

📚 License

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

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

🙏 Acknowledgement