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