vite-plugin-vitepress-auto-sidebar

The vite plugin that automatically generates sidebar data by scanning directories, based on vitepress

✨ Feature

🚀 Automatically create the sidebar data and injected into config.ThemeConfig.sidebar

🤖 Listen globally for *.md files to automatically update sidebar data when they are added or deleted

🕯️ Usage

install vite-plugin-vitepress-auto-sidebar

# recommend using pnpm packageManager
pnpm i vite-plugin-vitepress-auto-sidebar
# or yarn
yarn add vite-plugin-vitepress-auto-sidebar
# or npm
npm install vite-plugin-vitepress-auto-sidebar

add plugin in .vitepress/config.ts

import AutoSidebar from 'vite-plugin-vitepress-auto-sidebar';

export default defineConfig({
  vite: {
    plugins: [
      // add plugin
      AutoSidebar({
        // You can also set options to adjust sidebar data
        // see option document below
      })
    ]
  },
})

Warning, you must clear the sidebar objects in the config.ts or it may not work properly

pnpm run dev

 [auto-sidebar] injected sidebar data successfully

If you see the above message, it means the plugin is working properly, otherwise there may be a problem

🛠️ Options

Parameters

| name | description | type | default | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------- | | ignoreList | ignore specified folder | string[] | true | | path | create scan path for the sidebar | string | /docs | | scanRootMdFiles | scan the md file in path | boolean | true | | ignoreIndexItem | ignore the page sidebar with only index.md | boolean | false | | collapsed | By adding collapsed option to the sidebar group, it shows a toggle button to hide/show each section,For specific usage, please refer to VitePress | boolean | false | | deletePrefix | deletes the md file prefix | string | | | titleFromFile | read title from md file | boolean | false | | titleFromFileByYaml | read title from yaml config | boolean | false | | indexAliasFromFile | read sidebar-stack alias name from index.md | boolean | false | | indexFileUseTitleName | let index.md use its title as name in sidebar or not. | boolean | false |

Tips: about indexAliasFromFile

This tries to get value of alias from frontmatter of index.md. If not presented, uses first h1 headline as alias. If also not presented, skip alias.

A valid frontmatter for alias should like:

---
#...other attributes
alias: Example
---

Tips: about indexFileUseTitleName

If true, will override ignoreIndexItem as false.

Hooks

You can change the injected sidebar object using the hooks parameter

| name | description | type | default | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------- | | sideBarResolved | receive complete sidebar objects for custom modifications | (data: DefaultTheme.SidebarMulti) => DefaultTheme.SidebarMulti | | | sideBarItemsResolved | receive complete sidebar subItem objects for custom modifications | (data: DefaultTheme.SidebarItem[]) => DefaultTheme.SidebarItem[] | | | beforeCreateSideBarItems | obtain a list of file names scanned before generating sidebar subitems. If you want to sort sidebar data, it is recommended to use it | (data: string[]) => string[] | |

License

MIT License © 2023 QC2168