🔌 VitePress Sidebar

VitePress Sidebar is a plugin for VitePress that automatically configures and manages the sidebar of your page with simple settings.

• ⚡️ Optimized for the latest version of VitePress
• ⚡️ Easy to use, lots of options to customize to your liking
• ⚡️ Lightweight bundle file size, zero dependencies
• ⚡️ Multiple Sidebars support
• ⚡️ Frontmatter support
• ⚡️ TypeScript support
• ⚡️ Customize menus for sorting, special character conversion, file and folder filters, and more

Demo & Real-world Uses

VitePress Sidebar is utilized in a variety of project environments, including my own web services.

• An example homepage can be found here: https://vitepress-sidebar.jooy2.com
• To explore packages used other than: https://github.com/jooy2/vitepress-sidebar/network/dependents

To run and test the demo locally, clone this project and run the following commands:

$ npm i
$ npm run docs:dev

Installation

We recommend using Node.js 18.x or higher. The VitePress Sidebar is written in ESM. To use it in CommonJS, see instructions here.

# via npm
$ npm i -D vitepress-sidebar

# via yarn
$ yarn add -D vitepress-sidebar

# via pnpm
$ pnpm i -D vitepress-sidebar

How to Use

In the themeConfig setting of .vitepress/config.js file, execute the autoGenerate function as shown below to automatically generate the sidebar.

For more information about the configuration of generateSidebar, see Options section below.

import { generateSidebar } from 'vitepress-sidebar';

export default {
  themeConfig: {
    sidebar: generateSidebar({
      /*
       * For detailed instructions, see the links below:
       * https://github.com/jooy2/vitepress-sidebar#options
       */
      // documentRootPath: '/',
      // scanStartPath: null,
      // resolvePath: null,
      // useTitleFromFileHeading: true,
      // useTitleFromFrontmatter: true,
      // useFolderTitleFromIndexFile: false,
      // useFolderLinkFromIndexFile: false,
      // hyphenToSpace: true,
      // underscoreToSpace: true,
      // capitalizeFirst: false,
      // capitalizeEachWords: false,
      // collapsed: true,
      // collapseDepth: 2,
      // sortMenusByName: false,
      // sortMenusByFrontmatterOrder: false,
      // sortMenusOrderByDescending: false,
      // sortMenusOrderNumerically: false,
      // frontmatterOrderDefaultValue: 0,
      // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
      // excludeFiles: ['first.md', 'secret.md'],
      // excludeFolders: ['secret-folder'],
      // includeDotFiles: false,
      // includeRootIndexFile: false,
      // includeFolderIndexFile: false,
      // includeEmptyFolder: false,
      // rootGroupText: 'Contents',
      // rootGroupLink: 'https://github.com/jooy2',
      // rootGroupCollapsed: false,
      // convertSameNameSubFileToGroupIndexPage: false,
      // folderLinkNotIncludesFileName: false,
      // keepMarkdownSyntaxFromTitle: false,
      // debugPrint: false,
    })
  }
};

Example output:

generateSidebar({
  documentRootPath: 'example',
  scanStartPath: 'javascript',
  useTitleFromFileHeading: true,
  hyphenToSpace: true,
  excludeFolders: ['vitepress-how-to']
});

/*
[
  {
    text: 'examples',
    items: [
      {
        text: 'Examples',
        link: '/javascript/examples/examples'
      }
    ]
  },
  {
    text: 'functions',
    items: [
      {
        text: 'prototypes',
        items: [
          {
            text: 'Array',
            items: [
              {
                text: 'Array.indexOf',
                link: '/javascript/functions/prototypes/Array/Array.indexOf'
              }
            ]
          }
        ]
      }
    ]
  },
  {
    text: 'Getting Started',
    link: '/javascript/getting_started'
  }
];
*/

Options

documentRootPath

• Type: string
• Default: '/'

The top-level path where documentation files are located. The default value is /.

This is the path where the .vitepress directory is located, and if the folder where the documentation is located in the project root is /docs, then the value of this option should be set to docs or /docs.

/
├─ package.json
├─ src/
├─ docs/        <--------------- `documentRootPath` ('/docs')
│  ├─ .vitepress/        <------ VitePress config directory
│  ├─ another-directory/
│  ├─ hello.md
│  └─ index.md
└─ ...

scanStartPath

• Type: string|null
• Default: null

This option is used to configure Multiple Sidebars. See the Multiple Sidebars How-to section in README.md.

The path to the root directory to scan for document lists. Files in the path set in documentRootPath outside the path set in scanStartPath will not be scanned. It is recommended that you also set documentRootPath if you specify scanStartPath because the parent path set in documentRootPath should appear in the link.

For example, if the root path is /docs and the document to be scanned is /docs/sub-dir/scan-me, the setting would look like this:

• documentRootPath: /docs,
• scanStartPath: sub-dir/scan-me (Do not include the path to documentRootPath.)

resolvePath

• Type: string|null
• Default: null

This option is used to configure Multiple Sidebars. See the Multiple Sidebars How-to section in README.md.

Enter the path to the section to display a different sidebar for each path. The path must contain / before and after it. Options without this value will be set to the root section (/).

e.g. /, /path/sub-path, /guide/...

useTitleFromFileHeading

• Type: boolean
• Default: false

If the value is true, display the title with the h1 heading content of the .md file. If the h1 heading does not exist in the file, it displays Unknown.

The default menu items are sorted in folder tree order, so set the sortMenusByName option to true if you want to re-sort by the changed menu name.

useTitleFromFrontmatter

• Type: boolean
• Default: false

If the value is true, display the title based on the value of title in Frontmatter in the file. If this value cannot be parsed, it will be taken from the h1 tag if the useTitleFromFileHeading option is true, and from the filename if that fails.

The Frontmatter should be located at the top of the document, and should look like this (Space is required between the title: value and the title.)

---
title: This is frontmatter title value.
---

For more information, see the following articles: https://vitepress.dev/guide/frontmatter

The default menu items are sorted in folder tree order, so set the sortMenusByName option to true if you want to re-sort by the changed menu name.

useFolderTitleFromIndexFile

• Type: boolean
• Default: false

If this value is true, use the information in the current folder's index.md file to get the menu name. If the index.md file does not exist, the folder name is used. Since we typically get the name index from the index.md file, we recommend using the useTitleFromFileHeading or useTitleFromFrontmatter options together to get the title from the Markdown header or Frontmatter of that file.

The index.md file is hidden from the sidebar menu, but the index file can be shown in the menu if the includeFolderIndexFile option is true.

useFolderLinkFromIndexFile

• Type: boolean
• Default: false

If this value is true, specifies a link to the folder so that you can navigate to the index.md file in the current folder. If the index.md file does not exist, no link is created.

The index.md file is hidden from the sidebar menu, but the index file can be shown in the menu if the includeFolderIndexFile option is true.

manualSortFileNameByPriority

• Type: Array<string>
• Default: []

Sort by an array of file names (including extensions) in order. If there is no value in the array that matches the filename, the sort priority is sent back. This applies to both files and directories, and the same arrangement rules apply to subdirectories as well.

sortMenusByName

• Type: boolean
• Default: false

Sort the items in the menu item by name. Normally, folder scans are done with an ascending name sort, so the default sort is applied without this option applied, but if you use the useTitleFromFileHeading or useTitleFromFrontmatter options, you may need to re-sort by name because the menu name changes. This option forces sorting by name even for changed menu names.

sortMenusByFrontmatterOrder

• Type: boolean
• Default: false

Sorts the menu items by the order property of the frontmatter. For each folder, sorts the value (number) of the order property in ascending order, or descending order if the sortMenusOrderByDescending option is true. If the value of order is non-numeric or does not exist, order is judged to be 0.

sortMenusOrderByDescending

• Type: boolean
• Default: false

If this value is true, sorts the items in the menu item in descending order. This option is only enabled when sortMenusByName or sortMenusByFrontmatterOrder is true.

sortMenusOrderNumerically

• Type: boolean
• Default: false

If this value is true, If a menu name contains a number at the beginning, it is sorted by the lower number, not the name. For example, if you have files named 1-a, 10-a, and 2-a, a normal sort would sort by name, ['1-a', '10-a', '2-a']. This causes the menu to display in an unintended order because 10-a takes precedence over 2-a.

With this option, they are sorted as follows: ['1-a', '2-a', '10-a']

It should be used with the sortMenusOrderByDescending option if you want a descending sort.

frontmatterOrderDefaultValue

• Type: number
• Default: 0

Sets the default value for the order property of the frontmatter when not set. This option is only enabled when sortMenusByFrontmatterOrder is true.

collapsed

• Type: boolean
• Default: false

If the collapsed option is not specified(null or undefined), group collapse/expand is not used and all menus are displayed at once. If false, the menu is created with all groups expanded. If true, the menu is created with all groups collapsed.

collapseDepth

• Type: number
• Default: 1

At the specified depth, the menu group is made collapsed. When this option is specified, group collapsing/expanding is automatically enabled. The depth of the top-level folder is 1.

hyphenToSpace

• Type: boolean
• Default: false

If the value is true, the - symbol included in the file name is converted to a space and displayed as a title. This option is also affected when the menu name is imported via a MarkDown heading or frontmatter.

underscoreToSpace

• Type: boolean
• Default: false

If the value is true, the _ symbol included in the file name is converted to a space and displayed as a title. This option is also affected when the menu name is imported via a MarkDown heading or frontmatter.

capitalizeFirst

• Type: boolean
• Default: false

If the value is true, the first letter of the menu name is forced to uppercase. This option is also affected when the menu name is imported via a MarkDown heading or frontmatter.

capitalizeEachWords

• Type: boolean
• Default: false

If the value is true, Capitalize all first letters of words separated by spaces. This option is also affected when the menu name is imported via a MarkDown heading or frontmatter.

excludeFiles

• Type: Array<string>
• Default: []

Files that correspond to an array of file names (including extensions) are not shown in the list.

excludeFolders

• Type: Array<string>
• Default: []

Folders that correspond to an array of folder names are not shown in the list, and any sub-items within a folder are also not shown.

includeDotFiles

• Type: boolean
• Default: false

Normally, if file and folder names contain a dot (.) in front of them, they are considered hidden and not shown in the list. However, if this option is true, it forces all hidden files and folders to be shown in the list.

includeEmptyFolder

• Type: boolean
• Default: false

If the value is true, also displays directories where no md file exists as a group.

includeRootIndexFile

• Type: boolean
• Default: false

If the value is true, also include the top-level path index.md file in the sidebar menu. Use the includeFolderIndexFile option to include the index file of the child items as well. (If the file does not exist, it is ignored.)

includeFolderIndexFile

• Type: boolean
• Default: false

If the value is true, also include the folder path index.md file in the sidebar menu. Use the includeRootIndexFile option to include the index file of the root item as well. (If the file does not exist, it is ignored.)

rootGroupText

• Type: string
• Default: 'Table of Contents'

rootGroup specifies the entire group for the menu, regardless of directory structure. This uses one menu step, so you should be careful about using it, and you can disable the rootGroup option if you don't need it. If you specify this value, you specify a name for the top-level menu.

rootGroupLink

• Type: string
• Default: null

For more information about rootGroup, see the rootGroupText option description. Specifying this value specifies a link to the rootGroup. If the value is empty, no link is added.

rootGroupCollapsed

• Type: boolean
• Default: null

For more information about rootGroup, see the rootGroupText option description. The rootGroupCollapsed option sets whether child items of the root group are expanded or not. If specified with the default value of null or undefined, the expand/collapse button is not displayed. If the value is true, the child items are displayed collapsed, and if false, they are expanded.

This option only applies to top-level item. For general item collapsibility, see the collapsed option.

convertSameNameSubFileToGroupIndexPage

• Type: boolean
• Default: false

If this value is true, then if a subfile with the same name as the folder exists, a link will be created in the folder to navigate to that file, and the file will not be displayed in the child item.

folderLinkNotIncludesFileName

• Type: boolean
• Default: false

If this value is true, when establishing a folder link, ignore the existence of child items and specify the link only as a folder path. This option is not commonly used and is utilized for rewrite rules. This option may need to be used in conjunction with other options where folder links are created.

keepMarkdownSyntaxFromTitle

• Type: boolean
• Default: false

If this value is true, preserves the Markdown syntax contained in the title text without removing it. Usually retains any highlighting or inline code. Hyperlink text is removed regardless of this option.

debugPrint

• Type: boolean
• Default: false

If this value is true, prints the objects created after execution to the console log. If you configured Multiple sidebars, it will output all sidebar results even if you only include one of the options.

Multiple Sidebars How-to

To learn more about multiple sidebars, see the articles below:

https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars

You can specify multiple configuration objects of type Array in the option value of the generateSidebar function. Each object value can have different settings. If you use the scanStartPath and resolvePath options together, you can configure multiple sidebars.

generateSidebar([
  {
    documentRootPath: 'example',
    scanStartPath: 'css',
    resolvePath: '/css/',
    useTitleFromFileHeading: true,
    excludeFiles: ['c-css.md']
  },
  {
    documentRootPath: 'example',
    scanStartPath: 'javascript',
    resolvePath: '/javascript/',
    useTitleFromFrontmatter: true,
    excludeFiles: ['package.json.md', 'helpful-links.md'],
    excludeFolders: ['examples', 'vitepress-how-to']
  }
]);

The values of these options are used in the results as follows:

{
  <resolvePath>: [
    {
      base: <resolvePath>,
      items: [{ text: 'My Document', link: 'document/hello' }] // `<scanStartPath>/document/hello`
    }
  ]
}

Here's an example of the output from the above setup:

{
  '/css/': {
    base: '/css/',
    items: [
      {
        text: 'A',
        link: 'a-css'
      },
      {
        text: 'B',
        link: 'b-css'
      }
    ]
  },
  '/javascript/': {
    base: '/javascript/',
    items: [
      {
        text: 'es-module',
        link: 'es-module'
      },
      {
        text: 'functions',
        items: [
          {
            text: 'prototypes',
            items: [
              {
                text: 'Array',
                items: [
                  {
                    text: 'Array.indexOf',
                    link: 'functions/prototypes/Array/Array.indexOf'
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        text: 'getting_started',
        link: 'getting_started'
      }
    ]
  }
}

Learn more about scanStartPath and resolvePath in the Options section of README.md.

Troubleshoot: ERR_REQUIRE_ESM

vitepress-sidebar is an ESM module. If your project is using CJS, you will need to convert it to an ESM module.

For more information about the ESM module, see below: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

To address these issues, there are several solutions below:

Solution A

If you are trying to use it with a CJS project, change the file extension from .js to .mjs and try again. You can define that you want to use the module script for a specific file.

Solution B

in the package.json file, add the line "type": "module" line. This may require the project to be converted to an ESM project.

{
  name: 'docs',
  type: 'module', // <-- Add this
  version: '1.0.0',
  scripts: {
    dev: 'vitepress dev src',
    build: 'vitepress build src',
    serve: 'vitepress serve src'
  }
}

Contribute

You can report issues on GitHub Issue Tracker. You can also request a pull to fix bugs and add frequently used features.

License

Copyright © 2022-2024 Jooy2 <[email protected]> Released under the MIT license.