Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/logicspark/vitepress-plugin-nested-sidebar
:electric_plug: VitePress Nested Sidebar is a developer-friendly plugin for generating nested sidebar for your VitePress. Support TypeScript.
https://github.com/logicspark/vitepress-plugin-nested-sidebar
sidebar sidebar-menu vite vitepress vitepress-plugin vitepress-plugin-sidebar vue vue3
Last synced: 1 day ago
JSON representation
:electric_plug: VitePress Nested Sidebar is a developer-friendly plugin for generating nested sidebar for your VitePress. Support TypeScript.
- Host: GitHub
- URL: https://github.com/logicspark/vitepress-plugin-nested-sidebar
- Owner: logicspark
- License: mit
- Created: 2023-08-09T05:07:50.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-08T08:37:18.000Z (about 1 year ago)
- Last Synced: 2024-11-13T12:25:10.527Z (4 days ago)
- Topics: sidebar, sidebar-menu, vite, vitepress, vitepress-plugin, vitepress-plugin-sidebar, vue, vue3
- Language: TypeScript
- Homepage:
- Size: 588 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
:electric_plug: Vitepress Plugin - Nested Sidebar
Generate Nested sidebar. Support Multiple Sidebar. Support TypeScript
Developed by [Logic Spark](https://logicspark.com) team
[][package-url]
[][typescript-url]
[](/LICENSE)
## :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
1. [![Typescript][typescript]][typescript-url]
2. [![Vite][vite]][vite-url]
## :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](https://nodejs.org/en)
- [Vitepress](https://vitepress.dev/)
_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
```sh
npm install vitepress-plugin-nested-sidebar
```
#### Other options
- yarn
```sh
yarn add vitepress-plugin-nested-sidebar
```
- pnpm
```sh
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](/example/default/.vitepress/config.mts) file:
```js
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](https://vitepress.dev/reference/default-theme-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](#basic-sidebar)
use `object` for [Multiple sidebar](#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
```javascript
[
{
text: string; /*optional*/ /*sidebar name*/
link: string; /*optional*/ /*link to .md file*/
collapsed: boolean; /*optional*/
}
]
```
## Multiple Sidebar
```javascript
{
['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
```js
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
```js
checkMultipleSidebar(sidebar:Object | Array)
```
**resetHeader** - Use to reset scroll position to the top
```js
resetHeader();
```
**filterSidebar** - Filter the sidebar
```js
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](https://vitepress.dev/guide/getting-started#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
```js
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](/example/default-and-custom/.vitepress/theme/Layout.vue) directory._
## :books: License
Distributed under the MIT License. See [`LICENSE`](/LICENSE) for more information.
Vitepress is licensed under MIT License. Click [here](https://github.com/vuejs/vitepress/blob/main/LICENSE) for more information.
## :pray: Acknowledgement
- [Vitepress](https://vitepress.dev/)
- [Img Shields](https://shields.io)
[Vitepress-url]: https://vitepress.dev/
[TypeScript]: https://img.shields.io/badge/typescript-007ACC?style=for-the-badge&logo=typescript&logoColor=white
[typescript-url]: https://www.typescriptlang.org/
[Html]: https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge&logo=html5&logoColor=white
[html-url]: https://www.w3schools.com/html/
[Css]: https://img.shields.io/badge/css3-%231572B6.svg?style=for-the-badge&logo=css3&logoColor=white
[css-url]: https://www.w3schools.com/css/
[Vue]: https://img.shields.io/badge/vue.js-42B883?style=for-the-badge&logo=vuedotjs&logoColor=white
[Vue-url]: https://vuejs.org/
[Vite]: https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge&logo=vite&logoColor=white
[vite-url]: https://vitejs.dev/
[package-url]: https://www.npmjs.com/package/vitepress-plugin-nested-sidebar