Changelog

1.40.0 (2026-09-05)

• A frontmatter field is now only read from the frontmatter block of a page. The reader fell back to scanning the whole file line by line whenever gray-matter returned nothing for a field, and never stopped at the closing delimiter, so a key: value line written anywhere in the content was read as if it were frontmatter. A page that documents a frontmatter — an order: 1 inside a fenced code block, or an exclude: true in an example — was mis-sorted, given the wrong title, or dropped from the sidebar entirely. The block is now the only thing scanned, and the fallback still applies when the frontmatter is not valid YAML. A field that is present is also used when its value is falsy, so order: 0 and exclude: false mean what they say instead of being treated as absent.
• sortMenusByFileDatePrefix now sorts. It read the date prefix with split instead of match, which returns the part before the date and is therefore always the empty string, so every comparison was NaN and the items were left in the order the directory happened to be read in. That order is the one the file system returns, so it only looked like a date order on a file system that returns its entries sorted, and was arbitrary elsewhere. A menu item that does not begin with a date carries nothing to sort by, and is now kept together with the other such items before the dated ones, instead of leaving the whole level unordered.
• documentRootPath and scanStartPath are now stripped from a link as the text they are, instead of as a regular expression. A ., a ( or a + in the name of a folder was read as a regular expression character, so a document root such as docs (v2) was left in every link and every menu item pointed at a page that does not exist. A scanStartPath is also read the same way whether or not it is written with a surrounding slash.
• A folder is now skipped for being called node_modules or .vitepress only when that is its name. The check matched those names anywhere in the absolute path of an entry, so a project that merely sits somewhere below a directory whose name holds one of them, such as ~/my-node_modules-docs, produced an empty sidebar with nothing to explain it.
• A prefixSeparator written as a regular expression no longer prints itself inside a menu title. A title holding more than one match was split and then re-joined with the regular expression, so a name such as 1.1.1-four-file became 11/\./1-four-file. The first match is now removed and nothing is re-joined, which is what the documentation describes. A match that does not open the title is also no longer moved to the front of it.
• removePrefixAfterOrdering can be used on its own again. It reported 'prefixSeparator' should not use empty string unless a prefixSeparator was written down as well, because the check ran before the documented default of '.' was applied. Only a separator that is written down and empty is an error now.
• sortMenusByFileCreateDate now reads the time a file was created instead of ctime, which is the last time the metadata of a file changed. A chmod, a rename or anything else that touched a file moved it to the end of the menu without its content having changed. A file system that records no creation time still falls back to ctime, which is the closest thing it has. Both this option and sortMenusByFileModifyDate also keep the time in milliseconds now, so two files written in the same second are ordered by which of them came first instead of being left in the order the directory was read in.
• useTitleFromFileHeading no longer reads a # written inside a fenced code block as the heading of a page. A shell snippet whose first line is a comment, such as # Install the package, became the title of any page that showed one before its own heading. A block is only closed by a fence of the same character and at least the same length, so a block that holds another one is read as the one block it is.
• withSidebar no longer writes to the VitePress configuration or to the sidebar options it is given. It replaced themeConfig.sidebar with an empty object, set debugPrint to false, and appended its dev-server plugin to the very vite.plugins array of the caller. VitePress evaluates its configuration again on every restart of the dev server, so that last one added the plugin once more each time. A configuration or an options object that is frozen, such as one written with as const, also no longer fails with Cannot assign to read only property.
• A folder is now scanned in the order of its names, instead of the order the file system happens to hand its entries back in. That order is sorted on some file systems and a hash order on others, so a project with no sorting option built a different sidebar depending on the machine it was built on, and sortMenusByFileDatePrefix and sortMenusByFileCreateDate fell back to it whenever two items compared equal. The comparison is by code unit rather than by locale, so the same project always builds the same sidebar. The documentation already described this order; only now is it the one that is actually used.
• A root group made by rootGroupLink or rootGroupCollapsed alone is now named Table of Contents, the default the documentation describes, instead of being left with no name at all. The default is only used where a root group is actually made, so a sidebar still gets one only when one of the rootGroup options asks for it.
• sortFolderTo now reads a folder as a folder even when it holds no items. It told the two apart by the items of a menu item, which a folder kept by includeEmptyFolder, linked through useFolderLinkFromIndexFile, or emptied by excludeByFolderDepth does not have, so such a folder was moved to the end with the files.
• Two sidebars that resolve to the same path are now reported. The second one replaced the first without a word, so a resolvePath written twice by mistake silently dropped a whole sidebar.
• followSymlinks no longer fails the build on a symbolic link that leads back into the scan. A link pointing at a directory above itself was followed until the operating system stopped it with ELOOP, which ended the build. Every directory on the way to the current one is now remembered by the path it really is, so a link that closes the circle is left out instead. A link pointing at nothing is skipped as well, rather than stopping the build with ENOENT.
• A documentRootPath or scanStartPath that does not exist is now reported by name, together with the working directory it was resolved from. The build used to stop at a bare ENOENT: scandir, which named neither the option that was wrong nor what it was resolved against.
• The declaration files of the package no longer import ./types.ts. Three source files imported their types with a .ts extension, which survives into the declaration file, and lib is not published, so those files named something the package does not ship. Nothing reachable from the entry point pointed at one of them, so it broke no one yet; a test now keeps it that way.
• Sorting no longer walks the items of a folder once for every level above it. The keys the sorting needs were removed from the whole subtree each time a level was sorted, which is work proportional to the depth of the tree for every item in it. Each level cleans up after itself instead. Alongside it, the type of a directory entry is now read together with the entry itself rather than looked up one statSync at a time, manualSortFileNameByPriority is read from a lookup instead of being searched per entry, the two collators are built once instead of once per folder, and looking for a dynamic route template stops at the first one found. Each of these is a small saving on its own; together they take a little off every build, and rather more off a deep tree, where the repeated walk cost the most.
• A paths loader is now given two minutes to resolve its routes. It is project code run in a child process, and one that never returned held the whole build open. The sidebar is then built without the generated pages, as it already is for a loader that fails.
• npm run build no longer reformats the sources it is about to build. It ran prettier --write first, which meant that prepare rewrote the working tree on every install, and that continuous integration silently repaired a formatting problem instead of reporting it. Formatting is checked by the new format:check script, which runs in continuous integration together with lint, neither of which was run there before.
• Each Markdown file is now read and parsed once per build instead of once per option that reads something from it. useTitleFromFileHeading, useTitleFromFrontmatter, frontmatterTitleFieldName, excludeFilesByFrontmatterFieldName, sortMenusByFrontmatterOrder and sortMenusByFrontmatterDate used to read and parse the same file again each, up to four times over. On a 2,000 page project the combination of those options went from about 300 ms to about 100 ms, and frontmatterTitleFieldName no longer reads every file twice when the field it names is absent.

1.39.0 (2026-08-18)

• useTitleFromFileHeading no longer reads a comment written inside the frontmatter as the heading of a page. A comment starts with #, exactly like an h1 does, so a line such as # https://vitepress.dev/reference/default-theme-home-page left at the top of a frontmatter became the title of the item. The frontmatter block is now removed before the content is read for a heading, and a file that holds no heading below it falls back to its file name, as it already did. The block is located by its delimiters, the way VitePress locates it, so it is removed even when what it holds is not valid YAML. (#223)
• sortMenusByFrontmatterOrder now compares the order of the frontmatter as a number instead of as text, so a negative or a decimal value is placed where its value belongs. -2 no longer comes after -1, and 2.25 no longer comes after 2.5. The sorting relied on the numeric option of Intl.Collator, which is a natural sort of the digit runs inside a string and reads neither a leading - as a sign nor a . as a decimal point, so it only agreed with numeric order for small positive integers. Sorting by a file name or a title is unaffected, as it is still the natural sort that is wanted there. An order that does not read as a number now falls back to frontmatterOrderDefaultValue, as the documentation describes, instead of being sorted as NaN. (#233)

1.38.0 (2026-08-06)

• Add sortMenusByCustomFunction option, which sorts the items of every folder with a function of your own, written in the form Array.prototype.sort expects. Each item being compared carries text, link, fileName, filePath, isDirectory, createDate, modifyDate and frontmatter, so an order can be decided from something the other options never read, such as a date kept in version control. The file times and the frontmatter are only read when the function accesses them. It decides the order of a whole folder by itself, so it cannot be used together with another sorting option, and a function cannot be written in JSON, so it is not available in a sidebar.config.json. (#188)
• withSidebar now honors the srcExclude of the VitePress configuration, so a page that is excluded from the build no longer has to be excluded a second time to keep it out of the sidebar. Its patterns are resolved from documentRootPath, exactly like VitePress resolves them from srcDir, and are applied on top of excludeByGlobPattern and the other exclusion options rather than replacing them. Excluding a dynamic route template excludes every page it generates. generateSidebar is not given the VitePress configuration, so it cannot read srcExclude. (#181)
• sortMenusOrderNumericallyFromLink now sorts a folder that has no link by its own path, instead of placing every such folder at one end of the list. Folders and files are ordered together by the number in their names even when the titles come from elsewhere, such as with useFolderTitleFromIndexFile and useTitleFromFileHeading. (#183)

1.37.0 (2026-08-05)

• A sidebar.config.json file placed in any folder now configures that folder and everything below it. The options it declares take priority over the options passed to withSidebar or generateSidebar, and documentRootPath can be omitted when such a file exists. (#166)
• The $folder key of a sidebar.config.json describes the folder it lives in (order, text, link) instead of its contents, and is not inherited by subfolders. A folder can now be ordered, named and linked without an index.md, and the position of a folder no longer depends on where its index.md sits inside it. (#197)
• Add includeDynamicRoutes option, which shows a dynamic route as the pages it generates instead of as the template file it is generated from. A parameter may appear in a folder name as well, and both a .paths.ts file and an asynchronous paths() function are supported. (#199)
• Add dynamicRouteTitleParam option, which names the route parameter that holds the sidebar title of a generated page. A title written as {{ $params.name }} in the template is resolved as well, and the order and date parameters are read by sortMenusByFrontmatterOrder and sortMenusByFrontmatterDate.
• Sorting options are no longer overwritten by the folders above them.

1.36.1 (2026-05-22)

• Fixed execution issues in versions 1.35.0 through 1.36.0

1.36.0 (2026-05-22)

NOTE: This version is broken. Please use 1.36.1 or later.

• Add collapseFromLevel option (#225)

1.35.0 (2026-05-22)

NOTE: This version is broken. Please use 1.36.1 or later.

• HMR is now supported so that the sidebar automatically refreshes when documents are added or updated in the development environment. (You must use withSidebar) (#159)

1.34.0 (2026-05-21)

• Fix the capitalize option behaves in such a way that it ignores the prefix (#231)
• If the h1 heading in the Markdown file cannot be retrieved, the file name is used instead of Unknown.
• Add sortMenusByFileModifyDate option (#229)
• Add sortMenusByFileCreateDate option

1.33.2 (2026-05-06)

• BREAKING CHANGES: Node.js version 20 is no longer supported. You must install version 22 or higher. (Installation is possible in Node.js 20, but compatibility is not guaranteed.)
• Upgrade package dependencies

1.33.1 (2025-11-29)

• BREAKING CHANGES: Node.js version 18 is no longer supported. You must install version 20 or higher.
• Upgrade package dependencies

1.33.0 (2025-07-24)

• BREAKING CHANGES: The excludePattern option has been renamed to excludeByGlobPattern. The old name is still available, but we plan to remove it in a future major release.
• Add excludeByFolderDepth option (#213)
• Removed references to deprecated options excludeFiles, excludeFolders, convertSameNameSubFileToGroupIndexPage

1.32.1 (2025-07-05)

• Fix Package build

1.32.0 (2025-07-05)

• Add followSymlinks option (#209)

1.31.1 (2025-03-13)

• Correct link processing for general files containing the index character (#201)

1.31.0 (2025-02-07)

• BREAKING CHANGES: The excludeFiles and excludeFolders options have now been completely removed and replaced with excludePattern.
• Handling decimals in frontmatter order sorting (#197)

1.30.2 (2024-12-07)

• Fix import of type declaration files

1.30.1 (2024-12-07)

NOTE: This version is broken. Please use 1.30.2 or later.

• Fix critical import issue

1.30.0 (2024-12-06)

NOTE: This version is broken. Please use 1.30.2 or later.

• BREAKING CHANGES: The type declarations have been separated into a separate file, which you may need to import from the 'vitepress-sidebar/types' file. In general, to use a type, use it like this: import type { VitePressSidebarOptions } from 'vitepress-sidebar/types'. You may also need to change the value of moduleResolution in the tsconfig.json file to: nodenext or node16 or Bundler

// Before
import { withSidebar, VitePressSidebarOptions } from 'vitepress-sidebar';
// After
import { withSidebar } from 'vitepress-sidebar';
import type { VitePressSidebarOptions } from 'vitepress-sidebar/types';

• BREAKING CHANGES: The functions in the source file have now been split into multiple files. If you imported the module as follows, you will need to modify your code. (import VitePressSidebar from 'vitepress-sidebar' -> import * as VitePressSidebar from 'vitepress-sidebar') You can ignore this if you've used something like import { withSidebar } from 'vitepress-sidebar' or import { generateSidebar } from 'vitepress-sidebar', unless it's a special case.
• Fix issues with invalid build files

1.29.1 (2024-12-06)

• Removes the top-level path from the link path only at the first depth. (#186)

1.29.0 (2024-11-01)

• Introduces the withSidebar function. It can be used instead of generateSidebar and can be declared at the defineConfig level instead of the themeConfig.sidebar level. You can still use generateSidebar going forward, but we recommend using withSidebar for easier setup.

1.28.0 (2024-10-25)

• Not using numbers as separators in capitalizeEachWords (#185)
• BREAKING CHANGES: convertSameNameSubFileToGroupIndexPage option was renamed to useFolderLinkFromSameNameSubFile (#184)
• BREAKING CHANGES: Some deprecated options have been removed entirely: excludeFilesByFrontmatter, sortMenusOrderNumerically, sortByFileName, root, includeEmptyGroup, withIndex, useFolderLinkAsIndexPage, useIndexFileForFolderMenuInfo. See the documentation page and the CHANGELOG.md file for replacement options.

1.27.1 (2024-09-26)

• Fix sortMenusByFrontmatterOrder not been sorted in numerical order but in string order (@Cryolitia)

1.27.0 (2024-09-19)

• Add sortFolderTo option (#173)
• Do not create an empty items array
• Now capitalizeEachWords separates them into words based on all special characters (#175)

1.26.2 (2024-09-19)

• Fix sorting by name to be case-insensitive (#177)

1.26.1 (2024-09-18)

• Fix failed to install node.js 18 (#180)

1.26.0 (2024-09-16)

• BREAKING CHANGES: The excludeFiles and excludeFolders options have been deprecated; use the excludePattern option instead, which corresponds to both custom files and folders with a glob pattern. Both options will be removed in the next major version.
• Add excludePattern option (Specify the files/folders to exclude with the glob file pattern) (#145)

1.25.4 (2024-09-16)

• Fix performing formatting on attribute text in some Markdown syntax or HTML tags (#176)

1.25.3 (2024-09-03)

• If convertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)

1.25.2 (2024-09-03)

This version may cause unintended behavior. Please ignore this version.

• Fix convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when set
• Use the title of the index file if convertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)

1.25.1 (2024-09-03)

• BREAKING CHANGES: The Options type for TypeScript has been renamed to VitePressSidebarOptions.
• Fix to avoid converting non-first letter items to lowercase when using capitalizeEachWords
• Support for specifying sidebar option types for TypeScript
• Documentation page domain now changed to vitepress-sidebar.cdget.com!
• Korean documentation support

1.25.0 (2024-08-22)

• Add basePath option
• Fix incorrect directory path when using rewrite and convertSameNameSubFileToGroupIndexPage option. (#146)

1.24.2 (2024-08-13)

• Fix index link is blank in multiple sidebars (#167)

1.24.1 (2024-07-31)

• If a link exists in the directory, it will appear in the menu regardless of the option
• Fix do not include index link when index.md file is shown (#147)
• More precise argument checking

1.24.0 (2024-07-06)

• Add frontmatterTitleFieldName option. When used with useTitleFromFrontmatter, the text field of sidebar will extract from the value of frontmatterTitleFieldName instead of default title field if it exists. (@liudonghua123)

1.23.2 (2024-05-16)

• Revert 5ed188e. do not warn 'use option together'

1.23.1 (2024-05-15)

• Warning against using the removePrefixAfterOrdering option and the useTitleFrom option together
• Fix to return full filename if separator is not present in filename when using removePrefixAfterOrdering option

1.23.0 (2024-05-13)

• BREAKING CHANGES: The excludeFilesByFrontmatter option is deprecated and replaced by the excludeFilesByFrontmatterFieldName option. You can now specify any field name you want, including Frontmatter's exclude field name, and documents will be excluded from the menu when that field value is true. Existing users should work fine with the following settings excludeFilesByFrontmatterFieldName: 'exclude'. For more information, see the documentation.
• Allow empty values or empty object options to be passed in

1.22.0 (2024-03-28)

• prefixSeparator now accepts regular expressions
• Add sortMenusByFileDatePrefix option

1.21.0 (2024-03-15)

• Add removePrefixAfterOrdering and prefixSeparator option
• Documentation enhancements

1.20.0 (2024-03-12)

• BREAKING CHANGES: The sortMenusOrderNumerically option has been split into the sortMenusOrderNumericallyFromTitle and sortMenusOrderNumericallyFromLink options. Therefore, the old option is deprecated. Renamed to allow you to sort by file title or link. For more information, see README.md.
• Add sortMenusByFrontmatterDate option
• Add sortMenusOrderNumericallyFromLink option
• In useFolderLinkFromIndexFile, show the path to index.md together
• Fix folders with only an index file are not recognized as empty

1.19.0 (2024-02-26)

• Add excludeFilesByFrontmatter option (@aslafy-z)

1.18.6 (2024-01-03)

• Fix typescript issue

1.18.5 (2023-12-11)

• Add frontmatterOrderDefaultValue option (@aslafy-z)
• Fix recursive sort of items (@aslafy-z)
• Retrieve ordering for top level folder indexes (@aslafy-z)

1.18.0 (2023-10-02)

• Add capitalizeEachWords option
• The option to modify menu names is also reflected correctly when pulling names from MarkDown heading, frontmatter.

1.17.0 (2023-09-26)

• Add sortMenusOrderNumerically option

1.16.5 (2023-09-22)

• Fix nested links being created in multiple sidebars

1.16.0 (2023-09-21)

• BREAKING CHANGES: The useIndexFileForFolderMenuInfo option has been split into the useFolderTitleFromIndexFile and useFolderLinkFromIndexFile options. Therefore, the old option is deprecated. You can now specify whether the folder menu should get its name and link from the index.md file, respectively. For more information, see README.md.
• Make sure the link to the index page is clearly marked (e.g., folder/ instead of folder/index).

1.15.0 (2023-09-19)

• Fix correct base url for multiple sidebars
• The rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.

1.14.0 (2023-09-18)

• NOTE: The options rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!
• Use a better algorithm for stripping formatting from titles that contain Markdown syntax

1.13.0 (2023-09-13)

• BREAKING CHANGES: The generator normally strips some of the Markdown syntax when using useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.
• Add debugPrint option
• Add keepMarkdownSyntaxFromTitle option
• Improved test example files

1.12.0 (2023-09-12)

• Add sortMenusByFrontmatterOrder option

1.11.0 (2023-08-24)

• BREAKING CHANGES: useFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfo
• BREAKING CHANGES: sortByFileName option was renamed to manualSortFileNameByPriority
• BREAKING CHANGES: The useFolderLinkAsIndexPage option now also gets the title information of the index.md file, so the name of the folder menu is set to the title of the index.md file
• The useFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder name
• Add sortMenusByName and sortMenusOrderByDescending options
• Added deprecated warning for changed option names

1.10.1 (2023-08-08)

• Fixed issue with rootGroupCollapsed option not being applied correctly

1.10.0 (2023-07-25)

• Add includeFolderIndexFile option
• Add useFolderLinkAsIndexPage option

1.9.5 (2023-07-25)

• Troubleshooting when links are not prefixed with /
• Allow null or undefined value for collapsed options

1.9.0 (2023-07-24)

• Add rootGroupCollapsed option. This option is separate from the collapsed option and allows you to set whether the RootGroup (the item displayed in the Table of Contents) is expanded or not. See README.md for more information.
• Correct behavior of collapseDepth

1.8.2 (2023-07-18)

• Remove unnecessary files
• Upgrade package dependencies
• Update README.md

1.8.1 (2023-06-15)

• Make sure to apply multi-sidebar settings for settings containing resolvePath

1.8.0 (2023-06-13)

• BREAKING CHANGES: The root option was renamed to documentRootPath.
• Support for multiple sidebars (Add scanStartPath and resolvePath option. Please read README.md file.)
• Improved multiple validation checks
• Improved Frontmatter inspections with special characters or newlines

1.7.5 (2023-05-28)

• Add folderLinkNotIncludesFileName option

1.7.0 (2023-05-28)

• BREAKING CHANGES: The withIndex option was renamed to includeRootIndexFile.
• BREAKING CHANGES: The includeEmptyGroup option was renamed to includeEmptyFolder.
• Add excludeFiles option
• Add excludeFolders option
• Add includeDotFiles option
• Parsing markdown h1 tag and frontmatter correctly

1.6.5 (2023-05-27)

• Fix convertSameNameSubFileToGroupIndexPage and rename option not working together

1.6.0 (2023-05-27)

• BREAKING CHANGES: The default value for hyphenToSpace is now false.
• Add convertSameNameSubFileToGroupIndexPage option: 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.
• Fixed issue with hyphenToSpace and underscoreToSpace options not being applied to directories
• Add rootGroupLink option

1.5.1 (2023-05-26)

• Add .mocharc.json, remove tsconfig.prod.json file in .npmignore

1.5.0 (2023-05-26)

• Add useTitleFromFrontmatter option. See README.md.
• useTitleFromFileHeading: Use only valid title values in titles that contain links

1.4.0 (2023-05-26)

• Fix TypeScript lint error
• Upgrade package dependencies

1.3.1 (2023-04-20)

• Fix build issue

1.3.0 (2023-04-20)

• Upgrade package dependencies
• Cleanup codes and update documentation

1.2.0 (2023-02-07)

• BREAKING CHANGES: The collapsible option has been removed by VitePress 1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configs
  • 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.
• Upgrade package dependencies

1.1.5 (2023-01-12)

• Remove CODE_OF_CONDUCT.md for npm release

1.1.4 (2023-01-12)

• Upgrade package dependencies

1.1.3 (2022-12-08)

• Upgrade package dependencies
• Add includeEmptyGroup option
• Do not include empty group by default

1.1.2 (2022-11-23)

• Upgrade package dependencies
• Fix README.md and codes indent

1.1.1 (2022-11-02)

• Fix capitalizeFirst bug

1.1.0 (2022-11-02)

• Add capitalizeFirst option
• Fix null check for option

1.0.9 (2022-11-02)

• Add sortByFileName option

1.0.8 (2022-11-02)

• Add collapseDepth option
• Fix correct import fs module
• Upgrade package dependencies

1.0.7 (2022-10-31)

• Fix execution order and cleanup codes
• Add .editorconfig file and reformat codes (Development only)

1.0.6 (2022-10-31)

• Add useTitleFromFileHeading option
• Upgrade package dependencies

1.0.5 (2022-10-27)

• Change require NodeJS version to 14
• Add mocha test (Development only)

1.0.4 (2022-10-25)

• First production release

0.1.0 ~ 1.0.3 (2022-10-25 / Alpha)

• Alpha release (Not tested. Do not use production.)