API
This page describes all the options in the VitePress Sidebar.
@ Quick search
| Resolving Paths | Grouping |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| rootGroupLink | |
| rootGroupCollapsed |
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.
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 todocumentRootPath.)
resolvePath
- Type:
string|null - Default:
null
This option is used to configure Multiple Sidebars. See the Multiple Sidebars How-to section.
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.
sortMenusByFileDatePrefix
- Type:
boolean - Default:
false
If the value is true, sorts by date prefix in the name of the menu item. The date format must be in the form YYYY-MM-DD (e.g. 2024-01-01-menu-name, 2024-01-02.menu-name...)
To remove date prefixes that remain in the menu text afterward, you can utilize the prefixSeparator and removePrefixAfterOrdering options.
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.
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.
sortMenusByFrontmatterDate
- Type:
boolean - Default:
false
Sorts the menu items by the date property of the frontmatter. It also sorts the date property values in ascending order by oldest date (or descending order if the ``option istrue) The date format must match YYYY-MM-DD or the JavaScript Date data type.
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.
sortMenusOrderNumericallyFromTitle
- 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.
sortMenusOrderNumericallyFromLink
- 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. This option is the same as sortMenusOrderNumericallyFromTitle, but sorts by links instead of file titles. Therefore, it cannot be used with the sortMenusOrderNumericallyFromTitle option.
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.
excludeFilesByFrontmatterFieldName
- Type:
string|null - Default:
null
Documents with the value of the specified frontmatter field name set to true are excluded from the menu.
If no option is specified or the option value is undefined, it is ignored.
For example, if the option value is exclude, documents whose content contains exclude: true are not displayed in the menu.
---
title: This article is excluded.
exclude: true
---
# Article
ContentDepending on the value of this option, you can use other names like draft, hide, etc. instead of exclude.
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.)
removePrefixAfterOrdering
- Type:
boolean - Default:
false
Removes a specific prefix from each menu title from the menu items that appear after everything is done. This is ideal if you want to sort by the number in the filename without using frontmatter's sorting, and you don't want that number to be visible in the menu.
For example, if prefixSeparator is the default (.), the following menus will be renamed as follows
- File name:
1.hello-> Menu name:hello - File name:
1.1.hello-> Menu name:1.hello - File name:
1-1.hello-> Menu name:hello
Removes letters only once based on the separator, so a child item like 1.1. should be used like 1-1.. Alternatively, you can set a regular expression on the prefixSeparator value to work around it.
Can be used with the prefixSeparator option. See that option's description for more information.
(Note A: prefix only affects the title, the link will use the file link as it is).
(Note B: This option is ignored if you use the useTitleFromFileHeading or useTitleFromFrontmatter options).
prefixSeparator
- Type:
string|RegExp - Default:
'.'
This option can only be used in conjunction with the removePrefixAfterOrdering option to remove the prefix.
Removes the first part of a specified number of characters (at least one) from the extracted menu text. For example, if the menu name is 1. Text, and you set the prefixSeparator value to . , the result will be just Text.
You can also use regular expressions. Values matching the regular expression are removed. For example, to remove the date before the string in 2024-01-01-hello, specify the prefixSeparator value as /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g. The result is hello.
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.