{"id":20526327,"url":"https://github.com/logicspark/vitepress-plugin-nested-sidebar","last_synced_at":"2025-07-10T02:34:26.579Z","repository":{"id":193436752,"uuid":"676389804","full_name":"logicspark/vitepress-plugin-nested-sidebar","owner":"logicspark","description":":electric_plug: VitePress Nested Sidebar is a developer-friendly plugin for generating nested sidebar for your VitePress. Support TypeScript.","archived":false,"fork":false,"pushed_at":"2023-09-08T08:37:18.000Z","size":602,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T15:05:31.155Z","etag":null,"topics":["sidebar","sidebar-menu","vite","vitepress","vitepress-plugin","vitepress-plugin-sidebar","vue","vue3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/logicspark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-09T05:07:50.000Z","updated_at":"2024-11-04T20:24:55.000Z","dependencies_parsed_at":"2025-04-14T04:17:04.831Z","dependency_job_id":"a62b4016-b96f-4223-9092-5ed54ca67a1d","html_url":"https://github.com/logicspark/vitepress-plugin-nested-sidebar","commit_stats":null,"previous_names":["logicspark/vitepress-plugin-nested-sidebar"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/logicspark/vitepress-plugin-nested-sidebar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logicspark%2Fvitepress-plugin-nested-sidebar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logicspark%2Fvitepress-plugin-nested-sidebar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logicspark%2Fvitepress-plugin-nested-sidebar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logicspark%2Fvitepress-plugin-nested-sidebar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/logicspark","download_url":"https://codeload.github.com/logicspark/vitepress-plugin-nested-sidebar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/logicspark%2Fvitepress-plugin-nested-sidebar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264519717,"owners_count":23621857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["sidebar","sidebar-menu","vite","vitepress","vitepress-plugin","vitepress-plugin-sidebar","vue","vue3"],"created_at":"2024-11-15T23:13:40.574Z","updated_at":"2025-07-10T02:34:26.483Z","avatar_url":"https://github.com/logicspark.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca id=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e:electric_plug: Vitepress Plugin - Nested Sidebar\u003c/h1\u003e\n\nGenerate Nested sidebar. Support Multiple Sidebar. Support TypeScript\n\nDeveloped by [Logic Spark](https://logicspark.com) team\n\n[![npm](https://img.shields.io/npm/v/vitepress-plugin-nested-sidebar)][package-url]\n[![Typescript](https://img.shields.io/badge/typescript-100%25-blue)][typescript-url]\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](/LICENSE)\n\n\u003c/div\u003e\n\u003cbr/\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"#sunglasses_video-demo\"\u003eVideo Demo\u003c/a\u003e - \n  \u003ca href=\"#building_construction-built-with\"\u003eBuilt With\u003c/a\u003e - \n  \u003ca href=\"#rocket-getting-started\"\u003eGetting Started\u003c/a\u003e - \n  \u003ca href=\"#fire-usage\"\u003eUsage\u003c/a\u003e -\n  \u003ca href=\"#books-license\"\u003eLicense\u003c/a\u003e -\n  \u003ca href=\"#pray-acknowledgement\"\u003eAcknowledgement\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n## :sunglasses: Video Demo\n\nBasic Sidebar\n\nhttps://github.com/logicspark/vitepress-plugin-nested-sidebar/assets/135820109/bf64884f-3aff-4d2b-81f8-4a3cb41b923b\n\nMultiple Sidebar\n\nhttps://github.com/logicspark/vitepress-plugin-nested-sidebar/assets/135820109/ca50fa7f-7ce7-48ec-ac70-562e2471dd8b\n\n## :building_construction: Built With\n\n1. [![Typescript][typescript]][typescript-url]\n2. [![Vite][vite]][vite-url]\n\n## :rocket: Getting Started\n\n### Prerequisite\n\nThe plugin is created with Vite + TypeScript. To start using this library, please make sure to install the following external libraries first:\n\n- [Node.js](https://nodejs.org/en)\n- [Vitepress](https://vitepress.dev/)\n\n_Support Node.js 18.12.0 (LTS) and above_\n\n### Installation\n\nThere 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\n\n```sh\n  npm install vitepress-plugin-nested-sidebar\n```\n\n#### Other options\n\n- yarn\n\n```sh\n  yarn add vitepress-plugin-nested-sidebar\n```\n\n- pnpm\n\n```sh\n  pnpm add vitepress-plugin-nested-sidebar\n```\n\n## :fire: Usage\n\nYou will need to import `generateSidebar` function and `Layout.vue` file. Without `Layout.vue` file, the lib may not work properly.\n\n### Import generateSidebar Function\n\nYou will need to import function to `generateSidebar` menu under `themeConfig` setting of [.vitpress/config.mts](/example/default/.vitepress/config.mts) file:\n\n```js\nimport VitepressPluginNestedSidebar from \"vitepress-plugin-nested-sidebar\";\n```\n\n\u003c/div\u003e\n\n### Options of generateSidebar Function\n\nThere is one required option, `sidebars`. The option supports both native basic and multiple sidebars which are native to Vitepress.\n\n\\_Note: For more details of both types of sidebars, please check out [Sidebar](https://vitepress.dev/reference/default-theme-sidebar) of Vitepress documentation.\n\n| Options              | Type              | Required | Description                                                                                                                                                                                               |\n| -------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`sidebars`**       | `object`\\|`array` | Yes      | define sidebar menu name and link .md file in order to generate the headers \u003cbr/\u003e \u003cbr/\u003e use `array` for [Basic sidebar](#basic-sidebar)\u003cbr/\u003e \u003cbr/\u003e use `object` for [Multiple sidebar](#multiple-sidebar) |\n| **`excludeFile`**    | `array`           | Optional | exclude file to not to generate in the sidebar menu                                                                                                                                                       |\n| **`includeIndexMd`** | `boolean`         | Optional | generate the sidebar menu item from index.md                                                                                                                                                              |\n\n## Basic Sidebar\n\n```javascript\n[\n  {\n    text: string; /*optional*/ /*sidebar name*/\n    link: string; /*optional*/ /*link to .md file*/\n    collapsed: boolean; /*optional*/\n  }\n]\n```\n\n## Multiple Sidebar\n\n```javascript\n{\n  ['file':string]:{\n    text: string; /*optional*/\n    link: string; /*optional*/\n    collapsed: boolean; /*optional*/\n  }\n}\n```\n\n### Utility Functions\n\nThese 4 functions support the `generateSidebar` to work as intended:\n\n**calculateAndHighlightHeader** - Check for scroll position with respect to the nearest header\n\n```js\ncalculateAndHighlightHeader(\nheader:{\n  text,\n  link,\n  items,\n},\noptions:{\n  idName, /*optional /*in case of use another div to scroll*/\n  adjustOffsetTop /*optional*/\n})\n\n```\n\n**checkMultipleSidebar** - Check `themeConfig` sidebar if it is multiple or not\n\n```js\ncheckMultipleSidebar(sidebar:Object | Array)\n```\n\n**resetHeader** - Use to reset scroll position to the top\n\n```js\nresetHeader();\n```\n\n**filterSidebar** - Filter the sidebar\n\n```js\nfilterSidebar(compare:string)\n```\n\n#### Importance of Layout.vue\n\nThe 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.\n\n### Import Utility Functions from Theme\n\nPer Vitepress's [Setup Wizard](https://vitepress.dev/guide/getting-started#setup-wizard), there are three options\n\n1. Default Theme\n2. Default Theme + Customization\n3. Custom Theme\n\n#### Option 1: Default Theme\n\n1. Create `Layout.vue` and `index.ts` files\n2. Import the function into the `Layout.vue` file\n\n```js\nimport VitepressPluginNestedSidebar from \"vitepress-plugin-nested-sidebar\";\n\nconst { utility } = VitepressPluginNestedSidebar;\n\nconst {\n  calculateAndHighlightHeader,\n  resetHeader,\n  filterSidebar,\n  checkMultipleSidebar,\n} = utility;\n```\n\n_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._\n\n## :books: License\n\nDistributed under the MIT License. See [`LICENSE`](/LICENSE) for more information.\n\nVitepress is licensed under MIT License. Click [here](https://github.com/vuejs/vitepress/blob/main/LICENSE) for more information.\n\n## :pray: Acknowledgement\n\n- [Vitepress](https://vitepress.dev/)\n- [Img Shields](https://shields.io)\n\n[Vitepress-url]: https://vitepress.dev/\n[TypeScript]: https://img.shields.io/badge/typescript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\n[typescript-url]: https://www.typescriptlang.org/\n[Html]: https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge\u0026logo=html5\u0026logoColor=white\n[html-url]: https://www.w3schools.com/html/\n[Css]: https://img.shields.io/badge/css3-%231572B6.svg?style=for-the-badge\u0026logo=css3\u0026logoColor=white\n[css-url]: https://www.w3schools.com/css/\n[Vue]: https://img.shields.io/badge/vue.js-42B883?style=for-the-badge\u0026logo=vuedotjs\u0026logoColor=white\n[Vue-url]: https://vuejs.org/\n[Vite]: https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge\u0026logo=vite\u0026logoColor=white\n[vite-url]: https://vitejs.dev/\n[package-url]: https://www.npmjs.com/package/vitepress-plugin-nested-sidebar\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogicspark%2Fvitepress-plugin-nested-sidebar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flogicspark%2Fvitepress-plugin-nested-sidebar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flogicspark%2Fvitepress-plugin-nested-sidebar/lists"}