Best Pairings with VitePress
Optimized for the latest version of VitePress.
In a multi-level sidebar, the menu is displayed with indentation for each tier. However, VitePress starts indenting from the second tier by default. For example:
Above, directory-level-2 is a subfile of directory-level-1, but it appears to be in the same hierarchy.
This is not an issue with VitePress Sidebar, so to fix it, you'll need to customize the styling of your existing theme via VitePress' Custom CSS.
Create a theme directory in the .vitepress directory to override the styles required by the existing styles. Then, inside the theme directory, create an index.js file (If you're using Typescript, use index.ts instead of index.js) and a custom.css file.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...Then add the following to the index.js file:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;Next, add the following to the custom.css file:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}Now start the VitePress server. This will make it easier to see the hierarchy of the first level of the group where the child content exists.
It's important to note that the vertical divider you see here was only created with CSS; it should have been created as a div with a CSS class called indicator, so you should be aware that the vertical divider may not be selected when you build dynamic pages in the future.
In a multi-level sidebar, the menu is displayed with indentation for each tier. However, VitePress starts indenting from the second tier by default. For example:
Above, directory-level-2 is a subfile of directory-level-1, but it appears to be in the same hierarchy.
This is not an issue with VitePress Sidebar, so to fix it, you'll need to customize the styling of your existing theme via VitePress' Custom CSS.
Create a theme directory in the .vitepress directory to override the styles required by the existing styles. Then, inside the theme directory, create an index.js file (If you're using Typescript, use index.ts instead of index.js) and a custom.css file.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...Then add the following to the index.js file:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;Next, add the following to the custom.css file:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}Now start the VitePress server. This will make it easier to see the hierarchy of the first level of the group where the child content exists.
It's important to note that the vertical divider you see here was only created with CSS; it should have been created as a div with a CSS class called indicator, so you should be aware that the vertical divider may not be selected when you build dynamic pages in the future.
In a multi-level sidebar, the menu is displayed with indentation for each tier. However, VitePress starts indenting from the second tier by default. For example:
Above, directory-level-2 is a subfile of directory-level-1, but it appears to be in the same hierarchy.
This is not an issue with VitePress Sidebar, so to fix it, you'll need to customize the styling of your existing theme via VitePress' Custom CSS.
Create a theme directory in the .vitepress directory to override the styles required by the existing styles. Then, inside the theme directory, create an index.js file (If you're using Typescript, use index.ts instead of index.js) and a custom.css file.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...Then add the following to the index.js file:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;Next, add the following to the custom.css file:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}Now start the VitePress server. This will make it easier to see the hierarchy of the first level of the group where the child content exists.
It's important to note that the vertical divider you see here was only created with CSS; it should have been created as a div with a CSS class called indicator, so you should be aware that the vertical divider may not be selected when you build dynamic pages in the future.
Multiple sidebars is a feature that allows you to display different sidebar menus based on a specific URI path.
This is easily implemented in vitepress-sidebar with a few simple settings. In the end, VitePress will output the options as intended.
To learn more about Multiple sidebars first, we recommend taking a look at VitePress' official documentation below:
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
First, let's assume you have a root project called docs with subdirectories called guide and config, like this:
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdWhen the URL is located on a /guide page, the user wants the menu to show only the submenu of guide and hide the submenu of config. Similarly, you want to hide the submenu of guide when it is located on the /config page.
To implement this in vitepress-sidebar, you need to approach it differently from the existing setup.
Use the generateSidebar function as before, but pass an array. The array will contain at least one option from vitepress-sidebar. The values in the array can be as many URLs as you want to specify. Of course, you can also configure them with different settings.
// Must pass array arguments!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);The values of these options are used in the results as follows:
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}Here's an example of the output from the above setup:
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}The following options are available in Multiple sidebars: scanStartPath, basePath, and resolvePath. Each option is optional, but should be able to be used correctly depending on the situation.
Each option is described below. However, we recommend that you first refer to the descriptions of each option on the API page.
The descriptions below are based on the following examples:
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath This option is used to specify different directories as root paths for different routing rules. While documentRootPath is the root path that will actually be scanned (where the .vitepress directory is located), scanStartPath is the root path that should actually be seen in this route rule.
For example, to include only files in the /guide directory, specify the value of scanStartPath as guide. However, the path in documentRootPath should not be included.
resolvePath This option is used by VitePress to display the relevant menu when it encounters a specific URI. For example, if you want to display only the contents of the guide/api directory when reaching example.com/guide/api, the value of resolvePath would be /guide/api. It is recommended that you include / in front of the path.
This will usually have a similar value to scanStartPath, but sometimes you may need to specify it differently for i18n routing.
basePath This option is primarily utilized when working with VitePress' rewrite rules, and is optional otherwise.
It replaces the value of the base path in VitePress. If this value is not specified, the value of resolvePath or the root path (/) is specified.
If the actual path to the directory is different from the path structure in the URI, you should be able to navigate to the page provided by rewrite. Typically, the sidebar will generate a path based on the root directory and will not reference the rewrite path in VitePress.
For example, suppose you have a rewrite rule that looks like this:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});The guide/one.md document is displayed in the path to help/one. However, if you do this, the sidebar will not display the menu because it will try to find help/one, which is the path as it is.
To fix this, change the path in basePath to help:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- Add this
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});The above example is typically when the path is defined in steps, but when you want to show folders that are deep in steps, especially when the URI is shorter or uses different conventions than the actual folder path, you need to use additional methods. For example, you have a folder structure like this:
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdThis time, we want to show the menu in docs/guide/api when we reach the one-level URI /api. The expected menu is to show only api-one.md and api-two.md.
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);However, if you configure the options like this, you won't be able to display the menu, because the api directory is a subdirectory of guide. VitePress won't detect this and will navigate to a non-existent document.
To solve this, you need to use VitePress' Routing feature in parallel, see the article below for an explanation:
https://vitepress.dev/guide/routing#route-rewrites
Following the example above, we'll add the rewrites option to VitePress' config.js file, which should be located outside the themeConfig:
export default defineConfig({
+ /* [START] Add This */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] Add This */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});Now this will show a submenu of docs/guide/api when the URI path starts with /api!
Multiple sidebars is a feature that allows you to display different sidebar menus based on a specific URI path.
This is easily implemented in vitepress-sidebar with a few simple settings. In the end, VitePress will output the options as intended.
To learn more about Multiple sidebars first, we recommend taking a look at VitePress' official documentation below:
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
First, let's assume you have a root project called docs with subdirectories called guide and config, like this:
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdWhen the URL is located on a /guide page, the user wants the menu to show only the submenu of guide and hide the submenu of config. Similarly, you want to hide the submenu of guide when it is located on the /config page.
To implement this in vitepress-sidebar, you need to approach it differently from the existing setup.
Use the generateSidebar function as before, but pass an array. The array will contain at least one option from vitepress-sidebar. The values in the array can be as many URLs as you want to specify. Of course, you can also configure them with different settings.
// Must pass array arguments!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);The values of these options are used in the results as follows:
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}Here's an example of the output from the above setup:
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}The following options are available in Multiple sidebars: scanStartPath, basePath, and resolvePath. Each option is optional, but should be able to be used correctly depending on the situation.
Each option is described below. However, we recommend that you first refer to the descriptions of each option on the API page.
The descriptions below are based on the following examples:
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath This option is used to specify different directories as root paths for different routing rules. While documentRootPath is the root path that will actually be scanned (where the .vitepress directory is located), scanStartPath is the root path that should actually be seen in this route rule.
For example, to include only files in the /guide directory, specify the value of scanStartPath as guide. However, the path in documentRootPath should not be included.
resolvePath This option is used by VitePress to display the relevant menu when it encounters a specific URI. For example, if you want to display only the contents of the guide/api directory when reaching example.com/guide/api, the value of resolvePath would be /guide/api. It is recommended that you include / in front of the path.
This will usually have a similar value to scanStartPath, but sometimes you may need to specify it differently for i18n routing.
basePath This option is primarily utilized when working with VitePress' rewrite rules, and is optional otherwise.
It replaces the value of the base path in VitePress. If this value is not specified, the value of resolvePath or the root path (/) is specified.
If the actual path to the directory is different from the path structure in the URI, you should be able to navigate to the page provided by rewrite. Typically, the sidebar will generate a path based on the root directory and will not reference the rewrite path in VitePress.
For example, suppose you have a rewrite rule that looks like this:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});The guide/one.md document is displayed in the path to help/one. However, if you do this, the sidebar will not display the menu because it will try to find help/one, which is the path as it is.
To fix this, change the path in basePath to help:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- Add this
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});The above example is typically when the path is defined in steps, but when you want to show folders that are deep in steps, especially when the URI is shorter or uses different conventions than the actual folder path, you need to use additional methods. For example, you have a folder structure like this:
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdThis time, we want to show the menu in docs/guide/api when we reach the one-level URI /api. The expected menu is to show only api-one.md and api-two.md.
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);However, if you configure the options like this, you won't be able to display the menu, because the api directory is a subdirectory of guide. VitePress won't detect this and will navigate to a non-existent document.
To solve this, you need to use VitePress' Routing feature in parallel, see the article below for an explanation:
https://vitepress.dev/guide/routing#route-rewrites
Following the example above, we'll add the rewrites option to VitePress' config.js file, which should be located outside the themeConfig:
export default defineConfig({
+ /* [START] Add This */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] Add This */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});Now this will show a submenu of docs/guide/api when the URI path starts with /api!
convertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading optionconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading optionThis page describes all the options in the VitePress Sidebar.
| Resolving Paths | Grouping |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'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.
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress config directory\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
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 string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
Enter the path to the section to display a different sidebar for each path. The path must contain / before it. Options without this value will be set to the root section (/).
e.g. /, /path/sub-path, /guide/...
basePath string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
This option can be utilized if the path has changed due to VitePress's rewrite option. It replaces the base path in VitePress. If this value does not exist, it will use the value from resolvePath instead.
useTitleFromFileHeading booleanfalseIf 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 booleanfalseIf 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.)
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitleDisplays the menu title based on the key name in Frontmatter specified in the file. If the specified value does not exist in Frontmatter, the default title will be used as a fallback.
---\nname: This is frontmatter title value.\n---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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]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 booleanfalseSort 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 booleanfalseIf 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 booleanfalseSorts 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 booleanfalseSorts 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 sortMenusOrderByDescending option is true) The date format must match YYYY-MM-DD or the JavaScript Date data type.
sortMenusOrderByDescending booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 number0Sets the default value for the order property of the frontmatter when not set. This option is only enabled when sortMenusByFrontmatterOrder is true.
collapsed booleanfalseIf 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.
(Even if the value is true, the menu may be expanded if it is located in a document within a collapsed group.)
collapseDepth number1At 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]Files that correspond to an array of file names (including extensions) are not shown in the list.
excludeFilesByFrontmatterFieldName string|nullnullDocuments 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.
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContentDepending on the value of this option, you can use other names like draft, hide, etc. instead of exclude.
excludeFolders Array<string>[]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 booleanfalseNormally, 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 booleanfalseIf the value is true, also displays directories where no md file exists as a group.
includeRootIndexFile booleanfalseIf 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 booleanfalseIf 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 booleanfalseRemoves 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:
1.hello -> Menu name: hello1.1.hello -> Menu name: 1.hello1-1.hello -> Menu name: helloRemoves 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 string|RegExp'.'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 string'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 stringnullFor 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 booleannullFor 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 booleanfalseIf 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.
For example, if you have a folder that looks like this:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdA link is added to the api folder, and the api page in the api folder is not included in the menu listing. Clicking the link in the folder displays the file in api/api.md.
folderLinkNotIncludesFileName booleanfalseThis option is only used in special cases: when you have a rewrite rule and a subfile with the same folder name exists, use it in parallel with the convertSameNameSubFileToGroupIndexPage option.
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.
For example, if you have a folder that looks like this:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdWith the convertSameNameSubFileToGroupIndexPage option, clicking on the guide/api folder menu will take you to guide/api/api, but if you use the folderLinkNotIncludesFileName option with it, the link will be guide/api/.
keepMarkdownSyntaxFromTitle booleanfalseIf 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 booleanfalseIf 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.
This page describes all the options in the VitePress Sidebar.
| Resolving Paths | Grouping |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'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.
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress config directory\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
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 string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
Enter the path to the section to display a different sidebar for each path. The path must contain / before it. Options without this value will be set to the root section (/).
e.g. /, /path/sub-path, /guide/...
basePath string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
This option can be utilized if the path has changed due to VitePress's rewrite option. It replaces the base path in VitePress. If this value does not exist, it will use the value from resolvePath instead.
useTitleFromFileHeading booleanfalseIf 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 booleanfalseIf 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.)
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitleDisplays the menu title based on the key name in Frontmatter specified in the file. If the specified value does not exist in Frontmatter, the default title will be used as a fallback.
---\nname: This is frontmatter title value.\n---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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]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 booleanfalseSort 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 booleanfalseIf 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 booleanfalseSorts 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 booleanfalseSorts 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 sortMenusOrderByDescending option is true) The date format must match YYYY-MM-DD or the JavaScript Date data type.
sortMenusOrderByDescending booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 number0Sets the default value for the order property of the frontmatter when not set. This option is only enabled when sortMenusByFrontmatterOrder is true.
collapsed booleanfalseIf 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.
(Even if the value is true, the menu may be expanded if it is located in a document within a collapsed group.)
collapseDepth number1At 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]Files that correspond to an array of file names (including extensions) are not shown in the list.
excludeFilesByFrontmatterFieldName string|nullnullDocuments 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.
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContentDepending on the value of this option, you can use other names like draft, hide, etc. instead of exclude.
excludeFolders Array<string>[]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 booleanfalseNormally, 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 booleanfalseIf the value is true, also displays directories where no md file exists as a group.
includeRootIndexFile booleanfalseIf 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 booleanfalseIf 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 booleanfalseRemoves 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:
1.hello -> Menu name: hello1.1.hello -> Menu name: 1.hello1-1.hello -> Menu name: helloRemoves 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 string|RegExp'.'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 string'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 stringnullFor 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 booleannullFor 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 booleanfalseIf 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.
For example, if you have a folder that looks like this:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdA link is added to the api folder, and the api page in the api folder is not included in the menu listing. Clicking the link in the folder displays the file in api/api.md.
folderLinkNotIncludesFileName booleanfalseThis option is only used in special cases: when you have a rewrite rule and a subfile with the same folder name exists, use it in parallel with the convertSameNameSubFileToGroupIndexPage option.
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.
For example, if you have a folder that looks like this:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdWith the convertSameNameSubFileToGroupIndexPage option, clicking on the guide/api folder menu will take you to guide/api/api, but if you use the folderLinkNotIncludesFileName option with it, the link will be guide/api/.
keepMarkdownSyntaxFromTitle booleanfalseIf 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 booleanfalseIf 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.
This page walks you through the installation and use of the VitePress Sidebar module.
First, you may need to pre-configure VitePress before using this module.
We recommend using Node.js 18.x or higher. The VitePress Sidebar is written in ESM. To use it in CommonJS, see instructions here.
You will need to install the module using NPM or any other Node module package manager. The package should be installed in devDependencies as it is only used in the developer environment. Use the command below:
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebarYou can automatically generate a sidebar using the generateSidebar method of VitePress Sidebar.
It scans the folder against the given root path (documentRootPath), finds the markdown files before they were built by VitePress, and returns a menu generated based on the folder tree structure.
First, import vitepress-sidebar in one of the two ways below.
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};Use the generateSidebar method in the themeConfig.sidebar property of the .vitepress/config.js file, which is VitePress's configuration file. VitePress's configuration file might have a different filename or extension depending on your project's settings.
To test how this will output, try building VitePress with the debugPrint option set to true. You should see the output in the console.
For more information about the configuration of generateSidebar, see API section below.
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * For detailed instructions, see the links below:
+ * https://vitepress-sidebar.cdget.com/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/This page walks you through the installation and use of the VitePress Sidebar module.
First, you may need to pre-configure VitePress before using this module.
We recommend using Node.js 18.x or higher. The VitePress Sidebar is written in ESM. To use it in CommonJS, see instructions here.
You will need to install the module using NPM or any other Node module package manager. The package should be installed in devDependencies as it is only used in the developer environment. Use the command below:
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebarYou can automatically generate a sidebar using the generateSidebar method of VitePress Sidebar.
It scans the folder against the given root path (documentRootPath), finds the markdown files before they were built by VitePress, and returns a menu generated based on the folder tree structure.
First, import vitepress-sidebar in one of the two ways below.
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};Use the generateSidebar method in the themeConfig.sidebar property of the .vitepress/config.js file, which is VitePress's configuration file. VitePress's configuration file might have a different filename or extension depending on your project's settings.
To test how this will output, try building VitePress with the debugPrint option set to true. You should see the output in the console.
For more information about the configuration of generateSidebar, see API section below.
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * For detailed instructions, see the links below:
+ * https://vitepress-sidebar.cdget.com/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/VitePress Sidebar is a plugin for VitePress that automatically configures and manages the sidebar of your page with simple settings.
VitePress Sidebar is utilized in a variety of project environments, including my own web services.
VitePress Sidebar is a plugin for VitePress that automatically configures and manages the sidebar of your page with simple settings.
VitePress Sidebar is utilized in a variety of project environments, including my own web services.
다중 사이드바에서는 메뉴가 각 계층마다 들여쓰기로 표시됩니다. 그러나 VitePress는 기본적으로 두 번째 계층부터 들여쓰기를 시작합니다. 예를 들어:
위의 directory-level-2는 directory-level-1의 하위 파일이지만 같은 계층 구조에 있는 것으로 보입니다.
이 문제는 VitePress 사이드바의 문제가 아니므로 이 문제를 해결하려면 VitePress의 사용자 정의 CSS 기능을 사용하여 기존 테마의 스타일을 사용자 정의해야 합니다.
.vitepress 디렉토리에 theme 디렉토리를 만들어 기존 스타일에 필요한 스타일을 재정의합니다. 그런 다음 theme 디렉토리 안에 index.js 파일(타입스크립트를 사용하는 경우 index.js 대신 index.ts를 사용)과 custom.css 파일을 만듭니다.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ 이 줄 추가
+│ │ ├─ custom.css <------------ 이 줄 추가
+│ │ └─ index.js <------------ 이 줄 추가
+│ ├─ example.md
+│ └─ index.md
+└─ ...그런 다음 index.js 파일에 다음을 추가합니다:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;다음으로 custom.css 파일에 다음을 추가합니다:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}이제 VitePress 서버를 시작합니다. 이렇게 하면 하위 콘텐츠가 존재하는 그룹의 첫 번째 레벨의 계층 구조를 더 쉽게 확인할 수 있습니다.
여기에서 보이는 세로선은 CSS로만 생성된 것으로, indicator라는 CSS 클래스가 있는 div로 생성되어야 하므로 향후 동적 페이지를 작성할 때 세로선이 선택되지 않을 수 있다는 점에 유의해야 합니다.
다중 사이드바에서는 메뉴가 각 계층마다 들여쓰기로 표시됩니다. 그러나 VitePress는 기본적으로 두 번째 계층부터 들여쓰기를 시작합니다. 예를 들어:
위의 directory-level-2는 directory-level-1의 하위 파일이지만 같은 계층 구조에 있는 것으로 보입니다.
이 문제는 VitePress 사이드바의 문제가 아니므로 이 문제를 해결하려면 VitePress의 사용자 정의 CSS 기능을 사용하여 기존 테마의 스타일을 사용자 정의해야 합니다.
.vitepress 디렉토리에 theme 디렉토리를 만들어 기존 스타일에 필요한 스타일을 재정의합니다. 그런 다음 theme 디렉토리 안에 index.js 파일(타입스크립트를 사용하는 경우 index.js 대신 index.ts를 사용)과 custom.css 파일을 만듭니다.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ 이 줄 추가
+│ │ ├─ custom.css <------------ 이 줄 추가
+│ │ └─ index.js <------------ 이 줄 추가
+│ ├─ example.md
+│ └─ index.md
+└─ ...그런 다음 index.js 파일에 다음을 추가합니다:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;다음으로 custom.css 파일에 다음을 추가합니다:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}이제 VitePress 서버를 시작합니다. 이렇게 하면 하위 콘텐츠가 존재하는 그룹의 첫 번째 레벨의 계층 구조를 더 쉽게 확인할 수 있습니다.
여기에서 보이는 세로선은 CSS로만 생성된 것으로, indicator라는 CSS 클래스가 있는 div로 생성되어야 하므로 향후 동적 페이지를 작성할 때 세로선이 선택되지 않을 수 있다는 점에 유의해야 합니다.
다중 사이드바는 특정 URI 경로에 따라 서로 다른 사이드바 메뉴를 표시할 수 있는 기능입니다.
이것은 몇 가지 간단한 설정으로 vitepress-sidebar에서 쉽게 구현할 수 있습니다. 결국 VitePress는 의도한 대로 옵션을 출력합니다.
다중 사이드바에 대해 자세히 알아보려면 먼저 아래의 VitePress 공식 문서를 살펴보는 것이 좋습니다:
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
먼저, 다음과 같이 docs라는 루트 프로젝트와 guide 및 config라는 하위 디렉터리가 있다고 가정해 보겠습니다:
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdURL이 /guide 페이지에 있는 경우 사용자는 메뉴에 guide의 하위 메뉴만 표시하고 config의 하위 메뉴는 숨기기를 원합니다. 마찬가지로 /config 페이지에 guide의 하위 메뉴가 있을 때 하위 메뉴를 숨기려고 합니다.
이를 vitepress-sidebar에서 구현하려면 기존 설정과 다르게 접근해야 합니다.
이전과 같이 generateSidebar 함수를 사용하되 배열을 전달합니다. 배열에는 vitepress-sidebar의 옵션이 하나 이상 포함됩니다. 배열의 값은 원하는 만큼의 URL을 지정할 수 있습니다. 물론 다른 설정으로 구성할 수도 있습니다.
// 배열 인수를 전달해야 함!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);이러한 옵션의 값은 다음과 같이 결과에 사용됩니다:
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}다음은 위 설정의 출력 예시입니다:
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}다중 사이드바에서 사용할 수 있는 옵션은 다음과 같습니다: scanStartPath, basePath 및 resolvePath. 각 옵션은 선택 사항이지만 상황에 따라 올바르게 사용할 수 있어야 합니다.
각 옵션은 아래에 설명되어 있습니다. 그러나 먼저 API 페이지에서 각 옵션에 대한 설명을 참조하는 것이 좋습니다.
아래 설명은 다음 예시를 기반으로 합니다:
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath 이 옵션은 다른 라우팅 규칙의 루트 경로로 다른 디렉터리를 지정하는 데 사용됩니다. documenRootPath는 실제로 스캔할 루트 경로(.vitepress 디렉터리가 있는 위치)이고 scanStartPath는 이 경로 규칙에서 실제로 표시되어야 하는 루트 경로입니다.
예를 들어 /guide 디렉터리에 있는 파일만 포함하려면 scanStartPath의 값을 guide로 지정합니다. 단, documentRootPath의 경로는 포함되지 않아야 합니다.
resolvePath 이 옵션은 특정 URI를 발견했을 때 관련 메뉴를 표시하기 위해 VitePress에서 사용합니다. 예를 들어 example.com/guide/api에 도달할 때 guide/api 디렉토리의 내용만 표시하려면 resolvePath의 값은 /guide/api가 됩니다. 경로 앞에 /를 포함하는 것이 좋습니다.
이 값은 일반적으로 scanStartPath와 비슷한 값을 갖지만, i18n 라우팅을 위해 다르게 지정해야 하는 경우도 있습니다.
basePath 이 옵션은 주로 VitePress의 rewrite 규칙으로 작업할 때 사용되며, 그 외에는 선택 사항입니다.
VitePress에서 base 경로의 값을 대체합니다. 이 값을 지정하지 않으면 resolvePath 값 또는 루트 경로(/)가 지정됩니다.
디렉토리의 실제 경로가 URI의 경로 구조와 다른 경우 다시 쓰기를 통해 제공된 페이지로 이동할 수 있어야 합니다. 일반적으로 사이드바는 루트 디렉터리를 기반으로 경로를 생성하며 VitePress의 다시 쓰기 경로를 참조하지 않습니다.
예를 들어 다음과 같은 재작성 규칙이 있다고 가정해 보겠습니다:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});guide/one.md 문서가 help/one 경로에 표시됩니다. 그러나 이렇게 하면 사이드바가 경로인 help/one을 그대로 찾으려고 하기 때문에 메뉴가 표시되지 않습니다.
이 문제를 해결하려면 basePath의 경로를 help로 변경하세요:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- 이 라인을 추가합니다.
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});위의 예는 일반적으로 경로가 단계로 정의된 경우이지만, 단계가 깊은 폴더를 표시하려는 경우, 특히 URI가 더 짧거나 실제 폴더 경로와 다른 규칙을 사용하는 경우에는 추가 방법을 사용해야 합니다. 예를 들어 다음과 같은 폴더 구조가 있습니다:
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md이번에는 /api라는 한 단계 URI에 도달했을 때 docs/guide/api의 메뉴를 표시하고 싶습니다. 예상되는 메뉴는 api-one.md와 api-two.md만 표시하는 것입니다.
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);하지만 이렇게 옵션을 구성하면 api 디렉터리가 guide의 하위 디렉터리이기 때문에 메뉴를 표시할 수 없습니다. VitePress는 이를 감지하지 못하고 존재하지 않는 문서로 이동합니다.
이를 해결하려면 VitePress의 라우팅 기능을 병행해서 사용해야 합니다. 관련 내용은 아래 글을 참고하세요:
https://vitepress.dev/guide/routing#route-rewrites
위의 예에 따라 themeConfig 외부에 있어야 하는 VitePress 설정 파일인 config.js 파일에서 rewrites 옵션을 추가합니다:
export default defineConfig({
+ /* [START] 여기부터 */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] 여기까지 */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});이제 URI 경로가 /api로 시작하면 docs/guide/api의 하위 메뉴가 표시됩니다!
다중 사이드바는 특정 URI 경로에 따라 서로 다른 사이드바 메뉴를 표시할 수 있는 기능입니다.
이것은 몇 가지 간단한 설정으로 vitepress-sidebar에서 쉽게 구현할 수 있습니다. 결국 VitePress는 의도한 대로 옵션을 출력합니다.
다중 사이드바에 대해 자세히 알아보려면 먼저 아래의 VitePress 공식 문서를 살펴보는 것이 좋습니다:
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
먼저, 다음과 같이 docs라는 루트 프로젝트와 guide 및 config라는 하위 디렉터리가 있다고 가정해 보겠습니다:
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdURL이 /guide 페이지에 있는 경우 사용자는 메뉴에 guide의 하위 메뉴만 표시하고 config의 하위 메뉴는 숨기기를 원합니다. 마찬가지로 /config 페이지에 guide의 하위 메뉴가 있을 때 하위 메뉴를 숨기려고 합니다.
이를 vitepress-sidebar에서 구현하려면 기존 설정과 다르게 접근해야 합니다.
이전과 같이 generateSidebar 함수를 사용하되 배열을 전달합니다. 배열에는 vitepress-sidebar의 옵션이 하나 이상 포함됩니다. 배열의 값은 원하는 만큼의 URL을 지정할 수 있습니다. 물론 다른 설정으로 구성할 수도 있습니다.
// 배열 인수를 전달해야 함!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);이러한 옵션의 값은 다음과 같이 결과에 사용됩니다:
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}다음은 위 설정의 출력 예시입니다:
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}다중 사이드바에서 사용할 수 있는 옵션은 다음과 같습니다: scanStartPath, basePath 및 resolvePath. 각 옵션은 선택 사항이지만 상황에 따라 올바르게 사용할 수 있어야 합니다.
각 옵션은 아래에 설명되어 있습니다. 그러나 먼저 API 페이지에서 각 옵션에 대한 설명을 참조하는 것이 좋습니다.
아래 설명은 다음 예시를 기반으로 합니다:
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath 이 옵션은 다른 라우팅 규칙의 루트 경로로 다른 디렉터리를 지정하는 데 사용됩니다. documenRootPath는 실제로 스캔할 루트 경로(.vitepress 디렉터리가 있는 위치)이고 scanStartPath는 이 경로 규칙에서 실제로 표시되어야 하는 루트 경로입니다.
예를 들어 /guide 디렉터리에 있는 파일만 포함하려면 scanStartPath의 값을 guide로 지정합니다. 단, documentRootPath의 경로는 포함되지 않아야 합니다.
resolvePath 이 옵션은 특정 URI를 발견했을 때 관련 메뉴를 표시하기 위해 VitePress에서 사용합니다. 예를 들어 example.com/guide/api에 도달할 때 guide/api 디렉토리의 내용만 표시하려면 resolvePath의 값은 /guide/api가 됩니다. 경로 앞에 /를 포함하는 것이 좋습니다.
이 값은 일반적으로 scanStartPath와 비슷한 값을 갖지만, i18n 라우팅을 위해 다르게 지정해야 하는 경우도 있습니다.
basePath 이 옵션은 주로 VitePress의 rewrite 규칙으로 작업할 때 사용되며, 그 외에는 선택 사항입니다.
VitePress에서 base 경로의 값을 대체합니다. 이 값을 지정하지 않으면 resolvePath 값 또는 루트 경로(/)가 지정됩니다.
디렉토리의 실제 경로가 URI의 경로 구조와 다른 경우 다시 쓰기를 통해 제공된 페이지로 이동할 수 있어야 합니다. 일반적으로 사이드바는 루트 디렉터리를 기반으로 경로를 생성하며 VitePress의 다시 쓰기 경로를 참조하지 않습니다.
예를 들어 다음과 같은 재작성 규칙이 있다고 가정해 보겠습니다:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});guide/one.md 문서가 help/one 경로에 표시됩니다. 그러나 이렇게 하면 사이드바가 경로인 help/one을 그대로 찾으려고 하기 때문에 메뉴가 표시되지 않습니다.
이 문제를 해결하려면 basePath의 경로를 help로 변경하세요:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- 이 라인을 추가합니다.
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});위의 예는 일반적으로 경로가 단계로 정의된 경우이지만, 단계가 깊은 폴더를 표시하려는 경우, 특히 URI가 더 짧거나 실제 폴더 경로와 다른 규칙을 사용하는 경우에는 추가 방법을 사용해야 합니다. 예를 들어 다음과 같은 폴더 구조가 있습니다:
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md이번에는 /api라는 한 단계 URI에 도달했을 때 docs/guide/api의 메뉴를 표시하고 싶습니다. 예상되는 메뉴는 api-one.md와 api-two.md만 표시하는 것입니다.
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);하지만 이렇게 옵션을 구성하면 api 디렉터리가 guide의 하위 디렉터리이기 때문에 메뉴를 표시할 수 없습니다. VitePress는 이를 감지하지 못하고 존재하지 않는 문서로 이동합니다.
이를 해결하려면 VitePress의 라우팅 기능을 병행해서 사용해야 합니다. 관련 내용은 아래 글을 참고하세요:
https://vitepress.dev/guide/routing#route-rewrites
위의 예에 따라 themeConfig 외부에 있어야 하는 VitePress 설정 파일인 config.js 파일에서 rewrites 옵션을 추가합니다:
export default defineConfig({
+ /* [START] 여기부터 */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] 여기까지 */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});이제 URI 경로가 /api로 시작하면 docs/guide/api의 하위 메뉴가 표시됩니다!
convertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading optionconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading option이 페이지에서는 VitePress Sidebar의 모든 옵션에 대해 설명합니다.
| 경로 해석 | 그룹핑 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'문서 파일이 위치한 최상위 경로입니다. 기본값은 /입니다.
이 옵션은 .vitepress 디렉터리가 있는 경로이며, 프로젝트 루트에서 문서가 있는 폴더가 /docs인 경우 이 옵션의 값을 docs 또는 /docs로 설정해야 합니다.
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress 설정 디렉토리\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
문서 목록을 스캔할 루트 디렉터리 경로입니다. scanStartPath에 설정된 경로를 벗어난 documentRootPath에 설정된 경로에 있는 파일은 스캔되지 않습니다. documentRootPath에 설정된 상위 경로가 link에 표시되어야 하므로 scanStartPath를 지정하는 경우 documentRootPath도 함께 설정하는 것이 좋습니다.
예를 들어 루트 경로가 /docs이고 스캔할 문서가 /docs/sub-dir/scan-me인 경우, 설정은 다음과 같이 표시됩니다:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (documentRootPath 경로를 포함하지 마세요.)resolvePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
각 경로마다 다른 사이드바를 표시하려면 섹션의 경로를 입력합니다. 경로 앞에 /가 포함되어야 합니다. 이 값이 없는 옵션은 루트 섹션(/)으로 설정됩니다.
e.g. /, /path/sub-path, /guide/...
basePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
이 옵션은 VitePress의 rewrites 옵션으로 인해 경로가 변경된 경우에 사용할 수 있습니다. VitePress의 기본 경로를 대체합니다. 이 값이 존재하지 않으면 resolvePath의 값을 대신 사용합니다.
useTitleFromFileHeading booleanfalse값이 true이면 .md 파일의 h1 제목 내용이 포함된 제목을 표시합니다. 파일에 h1 제목이 존재하지 않으면 Unknown으로 표시됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useTitleFromFrontmatter booleanfalse값이 true이면 파일의 Frontmatter에 있는 title 값에 따라 제목을 표시합니다. 이 값을 구문 분석할 수 없는 경우 useTitleFromFileHeading 옵션이 true인 경우 h1 태그에서, 실패하면 파일 이름에서 가져옵니다.
'제목'은 문서 상단에 위치해야 하며 다음과 같이 표시되어야 합니다(title: 값과 제목 사이에 공백이 필요합니다).
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitle파일에 지정된 Frontmatter에서 지정한 키 이름을 기준으로 메뉴 제목을 표시합니다. 지정한 값이 Frontmatter에 존재하지 않으면 기본 title이 대체로 사용됩니다.
---\nname: 이 것은 Frontmatter의 제목값입니다.\n---자세한 내용은 다음 문서를 참조하세요: https://vitepress.dev/guide/frontmatter
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useFolderTitleFromIndexFile booleanfalse이 값이 true이면 현재 폴더의 index.md 파일에 있는 정보를 사용하여 메뉴 이름을 가져옵니다. 인덱스 파일이 존재하지 않으면 폴더 이름이 사용됩니다. 일반적으로 index라는 이름은 index.md 파일에서 가져오기 때문에 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 함께 사용하여 해당 파일의 마크다운 헤더 또는 프론트매터에서 제목을 가져오는 것이 좋습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
useFolderLinkFromIndexFile booleanfalse이 값이 true이면 현재 폴더에 있는 index.md 파일로 이동할 수 있도록 폴더에 대한 링크를 지정합니다. 인덱스 파일이 존재하지 않으면 링크가 생성되지 않습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
manualSortFileNameByPriority Array<string>[]파일 이름(확장자 포함) 배열을 순서대로 정렬합니다. 배열에 파일 이름과 일치하는 값이 없으면 정렬 우선순위가 반송됩니다. 이는 파일과 디렉터리 모두에 적용되며 하위 디렉터리에도 동일한 정렬 규칙이 적용됩니다.
sortMenusByName booleanfalse메뉴 항목의 항목을 이름별로 정렬합니다. 일반적으로 폴더 스캔은 오름차순 이름 정렬로 이루어지므로 이 옵션을 적용하지 않고 기본 정렬이 적용되지만, useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 메뉴 이름이 변경되어 이름별로 다시 정렬해야 할 수 있습니다. 이 옵션은 변경된 메뉴 이름에 대해서도 이름별로 강제로 정렬합니다.
sortMenusByFileDatePrefix booleanfalse값이 true이면 메뉴 항목 이름의 날짜 접두사를 기준으로 정렬합니다. 날짜 형식은 YYYY-MM-DD 형식이어야 합니다(예: 2024-01-01-menu-name, 2024-01-02.menu-name...).
이후 메뉴 텍스트에 남아있는 날짜 접두사를 제거하려면 prefixSeparator 및 removePrefixAfterOrdering 옵션을 활용하면 됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
sortMenusByFrontmatterOrder booleanfalse앞부분의 order 속성을 기준으로 메뉴 항목을 정렬합니다. 각 폴더에 대해 order 속성의 값(숫자)을 오름차순으로 정렬하거나, sortMenusOrderByDescending 옵션이 true인 경우 내림차순으로 정렬합니다. order 값이 숫자가 아니거나 존재하지 않는 경우 order는 0으로 판단됩니다.
sortMenusByFrontmatterDate booleanfalse앞부분의 date 속성을 기준으로 메뉴 항목을 정렬합니다. 또한 date 속성 값을 가장 오래된 날짜 순으로 오름차순으로 정렬합니다(sortMenusOrderByDescending 옵션이 true인 경우 내림차순). 날짜 형식은 YYYY-MM-DD 또는 JavaScript 날짜 데이터 유형과 일치해야 합니다.
sortMenusOrderByDescending booleanfalse이 값이 true이면 메뉴 항목의 항목을 내림차순으로 정렬합니다. 이 옵션은 sortMenusByName 또는 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
sortMenusOrderNumericallyFromTitle booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 예를 들어 1-a, 10-a, 2-a라는 이름의 파일이 있는 경우 일반 정렬에서는 ['1-a', '10-a', '2-a']라는 이름으로 정렬됩니다. 이렇게 하면 10-a가 2-a보다 우선하기 때문에 메뉴가 의도하지 않은 순서로 표시됩니다.
이 옵션을 사용하면 다음과 같이 정렬됩니다: ['1-a', '2-a', '10-a']
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
sortMenusOrderNumericallyFromLink booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 이 옵션은 sortMenusOrderNumericallyFromTitle과 동일하지만 파일 제목이 아닌 링크를 기준으로 정렬합니다. 따라서 sortMenusOrderNumericallyFromTitle 옵션과 함께 사용할 수 없습니다.
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
frontmatterOrderDefaultValue number0설정되지 않은 경우 앞부분의 order 속성에 대한 기본값을 설정합니다. 이 옵션은 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
collapsed booleanfalsecollapsed 옵션을 지정하지 않으면(null 또는 정의되지 않음) 그룹 접기/확장이 사용되지 않고 모든 메뉴가 한꺼번에 표시됩니다. false이면 모든 그룹이 확장된 상태로 메뉴가 생성됩니다. true이면 모든 그룹이 접힌 상태로 메뉴가 생성됩니다.
(값이 true이더라도 메뉴가 접힌 그룹 내의 문서에 있는 경우 메뉴가 확장될 수 있습니다.)
collapseDepth number1지정된 깊이에서 메뉴 그룹이 축소됩니다. 이 옵션을 지정하면 그룹 축소/확장이 자동으로 활성화됩니다. 최상위 폴더의 깊이는 1입니다.
hyphenToSpace booleanfalse값이 true이면 파일 이름에 포함된 - 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
underscoreToSpace booleanfalse값이 true이면 파일 이름에 포함된 _ 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeFirst booleanfalse값이 true이면 메뉴 이름의 첫 글자가 강제로 대문자로 바뀝니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeEachWords booleanfalse값이 true이면 공백으로 구분된 단어의 첫 글자를 모두 대문자로 표시합니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
excludeFiles Array<string>[]파일 이름 배열(확장자 포함)에 해당하는 파일은 목록에 표시되지 않습니다.
excludeFilesByFrontmatterFieldName string|nullnull지정된 앞부분 필드 이름의 값이 true로 설정된 문서는 메뉴에서 제외됩니다.
옵션이 지정되지 않았거나 옵션 값이 정의되지 않은 경우 무시됩니다.
예를 들어 옵션 값이 exclude인 경우 콘텐츠에 exclude: true가 포함된 문서는 메뉴에 표시되지 않습니다.
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContent이 옵션의 값에 따라 exclude 대신 draft, hide 등과 같은 다른 이름을 사용할 수 있습니다.
excludeFolders Array<string>[]폴더 이름의 배열에 해당하는 폴더는 목록에 표시되지 않으며, 폴더 내의 하위 항목도 표시되지 않습니다.
includeDotFiles booleanfalse일반적으로 파일 및 폴더 이름 앞에 점(.)이 있으면 숨겨진 것으로 간주되어 목록에 표시되지 않습니다. 하지만 이 옵션이 true이면 모든 숨겨진 파일과 폴더가 목록에 강제로 표시됩니다.
includeEmptyFolder booleanfalse값이 true인 경우, md 파일이 그룹으로 존재하지 않는 디렉터리도 표시합니다.
includeRootIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 최상위 경로 index.md 파일도 포함합니다. includeFolderIndexFile 옵션을 사용하여 하위 항목의 인덱스 파일도 포함합니다. (파일이 존재하지 않으면 무시됩니다.)
includeFolderIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 폴더 경로 index.md 파일도 포함합니다. 루트 항목의 인덱스 파일도 포함하려면 includeRootIndexFile 옵션을 사용합니다. (파일이 존재하지 않으면 무시됩니다.)
removePrefixAfterOrdering booleanfalse모든 작업이 완료된 후에 표시되는 메뉴 항목에서 각 메뉴 제목의 특정 접두사를 제거합니다. 이 옵션은 앞부분의 정렬을 사용하지 않고 파일 이름의 숫자를 기준으로 정렬하고 메뉴에 해당 숫자를 표시하지 않으려는 경우에 이상적입니다.
예를 들어 prefixSeparator가 기본값(.)인 경우 다음 메뉴의 이름이 다음과 같이 변경됩니다:
1.hello -> 메뉴명: hello1.1.hello -> 메뉴명: 1.hello1-1.hello -> 메뉴명: hello구분 기호에 따라 문자를 한 번만 제거하므로 1.1.과 같은 하위 항목은 1-1.처럼 사용해야 합니다. 또는 prefixSeparator 값에 정규식을 설정하여 이 문제를 해결할 수 있습니다.
prefixSeparator 옵션과 함께 사용할 수 있습니다. 자세한 내용은 해당 옵션의 설명을 참조하세요.
(참고: 접두사는 제목에만 영향을 미치며, 링크는 파일 링크를 그대로 사용합니다).
(참고 B: 이 옵션은 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 무시됩니다).
prefixSeparator string|RegExp'.'이 옵션은 접두사를 제거하기 위해 removePrefixAfterOrdering 옵션과 함께 사용할 때만 사용할 수 있습니다.
추출된 메뉴 텍스트에서 지정된 문자 수(하나 이상)의 첫 부분을 제거합니다. 예를 들어 메뉴 이름이 1. Text이고 prefixSeparator 값을 . '로 설정하면 결과는 Text`가 됩니다.
정규식을 사용할 수도 있습니다. 정규식과 일치하는 값은 제거됩니다. 예를 들어 2024-01-01-hello에서 문자열 앞의 날짜를 제거하려면 prefixSeparator 값을 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g로 지정합니다. 결과는 hello입니다.
rootGroupText string'Table of Contents'루트 그룹은 디렉토리 구조에 관계없이 메뉴의 전체 그룹을 지정합니다. 이 옵션은 하나의 메뉴 단계를 사용하므로 사용에 주의해야 하며, 필요하지 않은 경우 루트 그룹 옵션을 비활성화할 수 있습니다. 이 값을 지정하면 최상위 메뉴의 이름을 지정하는 것입니다.
rootGroupLink stringnull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. 이 값을 지정하면 루트 그룹에 대한 링크가 지정됩니다. 값이 비어 있으면 링크가 추가되지 않습니다.
rootGroupCollapsed booleannull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. rootGroupCollapsed 옵션은 루트 그룹의 하위 항목을 펼칠지 여부를 설정합니다. 기본값인 null 또는 정의되지 않음으로 지정하면 확장/축소 버튼이 표시되지 않습니다. 값이 true이면 하위 항목이 접힌 상태로 표시되고, false이면 확장됩니다.
이 옵션은 최상위 항목에만 적용됩니다. 일반적인 항목 축소 여부는 collapsed 옵션을 참조하세요.
convertSameNameSubFileToGroupIndexPage booleanfalse이 값이 true이면 폴더와 같은 이름의 하위 파일이 있는 경우 폴더에 해당 파일로 이동할 수 있는 링크가 생성되고 하위 항목에 해당 파일이 표시되지 않습니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdapi 폴더에 링크가 추가되며, api 폴더의 api 페이지는 메뉴 목록에 포함되지 않습니다. 폴더의 링크를 클릭하면 api/api.md에 파일이 표시됩니다.
folderLinkNotIncludesFileName booleanfalse이 옵션은 특별한 경우에만 사용됩니다. 다시 쓰기 규칙이 있고 폴더 이름이 같은 하위 파일이 있는 경우 convertSameNameSubFileToGroupIndexPage 옵션과 병렬로 사용합니다.
이 값이 true인 경우 폴더 링크를 설정할 때 하위 항목의 존재를 무시하고 링크를 폴더 경로로만 지정합니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdconvertSameNameSubFileToGroupIndexPage 옵션을 사용하면 guide/api 폴더 메뉴를 클릭하면 guide/api/로 이동하지만 folderLinkNotIncludesFileName 옵션을 함께 사용하면 guide/api/로 링크가 연결됩니다.
keepMarkdownSyntaxFromTitle booleanfalse이 값이 true이면 제목 텍스트에 포함된 마크다운 구문을 제거하지 않고 그대로 유지합니다. 일반적으로 강조 표시 또는 인라인 코드를 유지합니다. 하이퍼링크 텍스트는 이 옵션과 관계없이 제거됩니다.
debugPrint booleanfalse이 값이 true이면 실행 후 생성된 객체를 콘솔 로그에 출력합니다. 여러 사이드바를 구성한 경우 옵션 중 하나만 포함하더라도 모든 사이드바 결과를 출력합니다.
이 페이지에서는 VitePress Sidebar의 모든 옵션에 대해 설명합니다.
| 경로 해석 | 그룹핑 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'문서 파일이 위치한 최상위 경로입니다. 기본값은 /입니다.
이 옵션은 .vitepress 디렉터리가 있는 경로이며, 프로젝트 루트에서 문서가 있는 폴더가 /docs인 경우 이 옵션의 값을 docs 또는 /docs로 설정해야 합니다.
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress 설정 디렉토리\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
문서 목록을 스캔할 루트 디렉터리 경로입니다. scanStartPath에 설정된 경로를 벗어난 documentRootPath에 설정된 경로에 있는 파일은 스캔되지 않습니다. documentRootPath에 설정된 상위 경로가 link에 표시되어야 하므로 scanStartPath를 지정하는 경우 documentRootPath도 함께 설정하는 것이 좋습니다.
예를 들어 루트 경로가 /docs이고 스캔할 문서가 /docs/sub-dir/scan-me인 경우, 설정은 다음과 같이 표시됩니다:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (documentRootPath 경로를 포함하지 마세요.)resolvePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
각 경로마다 다른 사이드바를 표시하려면 섹션의 경로를 입력합니다. 경로 앞에 /가 포함되어야 합니다. 이 값이 없는 옵션은 루트 섹션(/)으로 설정됩니다.
e.g. /, /path/sub-path, /guide/...
basePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
이 옵션은 VitePress의 rewrites 옵션으로 인해 경로가 변경된 경우에 사용할 수 있습니다. VitePress의 기본 경로를 대체합니다. 이 값이 존재하지 않으면 resolvePath의 값을 대신 사용합니다.
useTitleFromFileHeading booleanfalse값이 true이면 .md 파일의 h1 제목 내용이 포함된 제목을 표시합니다. 파일에 h1 제목이 존재하지 않으면 Unknown으로 표시됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useTitleFromFrontmatter booleanfalse값이 true이면 파일의 Frontmatter에 있는 title 값에 따라 제목을 표시합니다. 이 값을 구문 분석할 수 없는 경우 useTitleFromFileHeading 옵션이 true인 경우 h1 태그에서, 실패하면 파일 이름에서 가져옵니다.
'제목'은 문서 상단에 위치해야 하며 다음과 같이 표시되어야 합니다(title: 값과 제목 사이에 공백이 필요합니다).
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitle파일에 지정된 Frontmatter에서 지정한 키 이름을 기준으로 메뉴 제목을 표시합니다. 지정한 값이 Frontmatter에 존재하지 않으면 기본 title이 대체로 사용됩니다.
---\nname: 이 것은 Frontmatter의 제목값입니다.\n---자세한 내용은 다음 문서를 참조하세요: https://vitepress.dev/guide/frontmatter
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useFolderTitleFromIndexFile booleanfalse이 값이 true이면 현재 폴더의 index.md 파일에 있는 정보를 사용하여 메뉴 이름을 가져옵니다. 인덱스 파일이 존재하지 않으면 폴더 이름이 사용됩니다. 일반적으로 index라는 이름은 index.md 파일에서 가져오기 때문에 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 함께 사용하여 해당 파일의 마크다운 헤더 또는 프론트매터에서 제목을 가져오는 것이 좋습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
useFolderLinkFromIndexFile booleanfalse이 값이 true이면 현재 폴더에 있는 index.md 파일로 이동할 수 있도록 폴더에 대한 링크를 지정합니다. 인덱스 파일이 존재하지 않으면 링크가 생성되지 않습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
manualSortFileNameByPriority Array<string>[]파일 이름(확장자 포함) 배열을 순서대로 정렬합니다. 배열에 파일 이름과 일치하는 값이 없으면 정렬 우선순위가 반송됩니다. 이는 파일과 디렉터리 모두에 적용되며 하위 디렉터리에도 동일한 정렬 규칙이 적용됩니다.
sortMenusByName booleanfalse메뉴 항목의 항목을 이름별로 정렬합니다. 일반적으로 폴더 스캔은 오름차순 이름 정렬로 이루어지므로 이 옵션을 적용하지 않고 기본 정렬이 적용되지만, useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 메뉴 이름이 변경되어 이름별로 다시 정렬해야 할 수 있습니다. 이 옵션은 변경된 메뉴 이름에 대해서도 이름별로 강제로 정렬합니다.
sortMenusByFileDatePrefix booleanfalse값이 true이면 메뉴 항목 이름의 날짜 접두사를 기준으로 정렬합니다. 날짜 형식은 YYYY-MM-DD 형식이어야 합니다(예: 2024-01-01-menu-name, 2024-01-02.menu-name...).
이후 메뉴 텍스트에 남아있는 날짜 접두사를 제거하려면 prefixSeparator 및 removePrefixAfterOrdering 옵션을 활용하면 됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
sortMenusByFrontmatterOrder booleanfalse앞부분의 order 속성을 기준으로 메뉴 항목을 정렬합니다. 각 폴더에 대해 order 속성의 값(숫자)을 오름차순으로 정렬하거나, sortMenusOrderByDescending 옵션이 true인 경우 내림차순으로 정렬합니다. order 값이 숫자가 아니거나 존재하지 않는 경우 order는 0으로 판단됩니다.
sortMenusByFrontmatterDate booleanfalse앞부분의 date 속성을 기준으로 메뉴 항목을 정렬합니다. 또한 date 속성 값을 가장 오래된 날짜 순으로 오름차순으로 정렬합니다(sortMenusOrderByDescending 옵션이 true인 경우 내림차순). 날짜 형식은 YYYY-MM-DD 또는 JavaScript 날짜 데이터 유형과 일치해야 합니다.
sortMenusOrderByDescending booleanfalse이 값이 true이면 메뉴 항목의 항목을 내림차순으로 정렬합니다. 이 옵션은 sortMenusByName 또는 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
sortMenusOrderNumericallyFromTitle booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 예를 들어 1-a, 10-a, 2-a라는 이름의 파일이 있는 경우 일반 정렬에서는 ['1-a', '10-a', '2-a']라는 이름으로 정렬됩니다. 이렇게 하면 10-a가 2-a보다 우선하기 때문에 메뉴가 의도하지 않은 순서로 표시됩니다.
이 옵션을 사용하면 다음과 같이 정렬됩니다: ['1-a', '2-a', '10-a']
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
sortMenusOrderNumericallyFromLink booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 이 옵션은 sortMenusOrderNumericallyFromTitle과 동일하지만 파일 제목이 아닌 링크를 기준으로 정렬합니다. 따라서 sortMenusOrderNumericallyFromTitle 옵션과 함께 사용할 수 없습니다.
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
frontmatterOrderDefaultValue number0설정되지 않은 경우 앞부분의 order 속성에 대한 기본값을 설정합니다. 이 옵션은 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
collapsed booleanfalsecollapsed 옵션을 지정하지 않으면(null 또는 정의되지 않음) 그룹 접기/확장이 사용되지 않고 모든 메뉴가 한꺼번에 표시됩니다. false이면 모든 그룹이 확장된 상태로 메뉴가 생성됩니다. true이면 모든 그룹이 접힌 상태로 메뉴가 생성됩니다.
(값이 true이더라도 메뉴가 접힌 그룹 내의 문서에 있는 경우 메뉴가 확장될 수 있습니다.)
collapseDepth number1지정된 깊이에서 메뉴 그룹이 축소됩니다. 이 옵션을 지정하면 그룹 축소/확장이 자동으로 활성화됩니다. 최상위 폴더의 깊이는 1입니다.
hyphenToSpace booleanfalse값이 true이면 파일 이름에 포함된 - 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
underscoreToSpace booleanfalse값이 true이면 파일 이름에 포함된 _ 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeFirst booleanfalse값이 true이면 메뉴 이름의 첫 글자가 강제로 대문자로 바뀝니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeEachWords booleanfalse값이 true이면 공백으로 구분된 단어의 첫 글자를 모두 대문자로 표시합니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
excludeFiles Array<string>[]파일 이름 배열(확장자 포함)에 해당하는 파일은 목록에 표시되지 않습니다.
excludeFilesByFrontmatterFieldName string|nullnull지정된 앞부분 필드 이름의 값이 true로 설정된 문서는 메뉴에서 제외됩니다.
옵션이 지정되지 않았거나 옵션 값이 정의되지 않은 경우 무시됩니다.
예를 들어 옵션 값이 exclude인 경우 콘텐츠에 exclude: true가 포함된 문서는 메뉴에 표시되지 않습니다.
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContent이 옵션의 값에 따라 exclude 대신 draft, hide 등과 같은 다른 이름을 사용할 수 있습니다.
excludeFolders Array<string>[]폴더 이름의 배열에 해당하는 폴더는 목록에 표시되지 않으며, 폴더 내의 하위 항목도 표시되지 않습니다.
includeDotFiles booleanfalse일반적으로 파일 및 폴더 이름 앞에 점(.)이 있으면 숨겨진 것으로 간주되어 목록에 표시되지 않습니다. 하지만 이 옵션이 true이면 모든 숨겨진 파일과 폴더가 목록에 강제로 표시됩니다.
includeEmptyFolder booleanfalse값이 true인 경우, md 파일이 그룹으로 존재하지 않는 디렉터리도 표시합니다.
includeRootIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 최상위 경로 index.md 파일도 포함합니다. includeFolderIndexFile 옵션을 사용하여 하위 항목의 인덱스 파일도 포함합니다. (파일이 존재하지 않으면 무시됩니다.)
includeFolderIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 폴더 경로 index.md 파일도 포함합니다. 루트 항목의 인덱스 파일도 포함하려면 includeRootIndexFile 옵션을 사용합니다. (파일이 존재하지 않으면 무시됩니다.)
removePrefixAfterOrdering booleanfalse모든 작업이 완료된 후에 표시되는 메뉴 항목에서 각 메뉴 제목의 특정 접두사를 제거합니다. 이 옵션은 앞부분의 정렬을 사용하지 않고 파일 이름의 숫자를 기준으로 정렬하고 메뉴에 해당 숫자를 표시하지 않으려는 경우에 이상적입니다.
예를 들어 prefixSeparator가 기본값(.)인 경우 다음 메뉴의 이름이 다음과 같이 변경됩니다:
1.hello -> 메뉴명: hello1.1.hello -> 메뉴명: 1.hello1-1.hello -> 메뉴명: hello구분 기호에 따라 문자를 한 번만 제거하므로 1.1.과 같은 하위 항목은 1-1.처럼 사용해야 합니다. 또는 prefixSeparator 값에 정규식을 설정하여 이 문제를 해결할 수 있습니다.
prefixSeparator 옵션과 함께 사용할 수 있습니다. 자세한 내용은 해당 옵션의 설명을 참조하세요.
(참고: 접두사는 제목에만 영향을 미치며, 링크는 파일 링크를 그대로 사용합니다).
(참고 B: 이 옵션은 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 무시됩니다).
prefixSeparator string|RegExp'.'이 옵션은 접두사를 제거하기 위해 removePrefixAfterOrdering 옵션과 함께 사용할 때만 사용할 수 있습니다.
추출된 메뉴 텍스트에서 지정된 문자 수(하나 이상)의 첫 부분을 제거합니다. 예를 들어 메뉴 이름이 1. Text이고 prefixSeparator 값을 . '로 설정하면 결과는 Text`가 됩니다.
정규식을 사용할 수도 있습니다. 정규식과 일치하는 값은 제거됩니다. 예를 들어 2024-01-01-hello에서 문자열 앞의 날짜를 제거하려면 prefixSeparator 값을 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g로 지정합니다. 결과는 hello입니다.
rootGroupText string'Table of Contents'루트 그룹은 디렉토리 구조에 관계없이 메뉴의 전체 그룹을 지정합니다. 이 옵션은 하나의 메뉴 단계를 사용하므로 사용에 주의해야 하며, 필요하지 않은 경우 루트 그룹 옵션을 비활성화할 수 있습니다. 이 값을 지정하면 최상위 메뉴의 이름을 지정하는 것입니다.
rootGroupLink stringnull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. 이 값을 지정하면 루트 그룹에 대한 링크가 지정됩니다. 값이 비어 있으면 링크가 추가되지 않습니다.
rootGroupCollapsed booleannull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. rootGroupCollapsed 옵션은 루트 그룹의 하위 항목을 펼칠지 여부를 설정합니다. 기본값인 null 또는 정의되지 않음으로 지정하면 확장/축소 버튼이 표시되지 않습니다. 값이 true이면 하위 항목이 접힌 상태로 표시되고, false이면 확장됩니다.
이 옵션은 최상위 항목에만 적용됩니다. 일반적인 항목 축소 여부는 collapsed 옵션을 참조하세요.
convertSameNameSubFileToGroupIndexPage booleanfalse이 값이 true이면 폴더와 같은 이름의 하위 파일이 있는 경우 폴더에 해당 파일로 이동할 수 있는 링크가 생성되고 하위 항목에 해당 파일이 표시되지 않습니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdapi 폴더에 링크가 추가되며, api 폴더의 api 페이지는 메뉴 목록에 포함되지 않습니다. 폴더의 링크를 클릭하면 api/api.md에 파일이 표시됩니다.
folderLinkNotIncludesFileName booleanfalse이 옵션은 특별한 경우에만 사용됩니다. 다시 쓰기 규칙이 있고 폴더 이름이 같은 하위 파일이 있는 경우 convertSameNameSubFileToGroupIndexPage 옵션과 병렬로 사용합니다.
이 값이 true인 경우 폴더 링크를 설정할 때 하위 항목의 존재를 무시하고 링크를 폴더 경로로만 지정합니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.mdconvertSameNameSubFileToGroupIndexPage 옵션을 사용하면 guide/api 폴더 메뉴를 클릭하면 guide/api/로 이동하지만 folderLinkNotIncludesFileName 옵션을 함께 사용하면 guide/api/로 링크가 연결됩니다.
keepMarkdownSyntaxFromTitle booleanfalse이 값이 true이면 제목 텍스트에 포함된 마크다운 구문을 제거하지 않고 그대로 유지합니다. 일반적으로 강조 표시 또는 인라인 코드를 유지합니다. 하이퍼링크 텍스트는 이 옵션과 관계없이 제거됩니다.
debugPrint booleanfalse이 값이 true이면 실행 후 생성된 객체를 콘솔 로그에 출력합니다. 여러 사이드바를 구성한 경우 옵션 중 하나만 포함하더라도 모든 사이드바 결과를 출력합니다.
이 페이지에서는 VitePress Sidebar 모듈의 설치 및 사용 방법을 안내합니다.
먼저 이 모듈을 사용하기 전에 VitePress 모듈을 사전 구성해야 할 수 있습니다.
Node.js 버전은 18.x 이상을 사용하는 것이 좋습니다. VitePress Sidebar는 ESM으로 작성되었습니다. CommonJS 환경에서 사용하려면 여기 지침을 참조하세요.
NPM 또는 다른 노드 모듈 패키지 관리자를 사용하여 모듈을 설치할 수 있습니다. 이 패키지는 개발자 환경에서만 사용되므로 devDependencies에 설치해야 합니다. 아래 명령어로 설치하세요:
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebarVitePress Sidebar의 generateSidebar 메서드를 사용하여 사이드바를 자동으로 생성할 수 있습니다.
지정된 루트 경로(documentRootPath)에 대해 폴더를 검색하고 VitePress에서 마크다운 파일을 작성하기 전에 찾은 다음 폴더 트리 구조에 따라 생성된 메뉴를 반환합니다.
먼저 아래 두 가지 방법 중 하나로 vitepress-sidebar를 import합니다.
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};VitePress의 구성 파일인 .vitepress/config.js 파일의 themeConfig.sidebar 속성에서 generateSidebar 메서드를 사용합니다. VitePress의 구성 파일은 프로젝트 설정에 따라 파일 이름이나 확장자가 다를 수 있습니다.
이것이 어떻게 출력되는지 테스트하려면 debugPrint 옵션을 true로 설정하여 VitePress를 빌드해 보세요. 콘솔에 출력이 표시될 것입니다.
generateSidebar의 설정에 대한 자세한 내용은 아래 API 섹션을 참조하세요.
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * For detailed instructions, see the links below:
+ * https://vitepress-sidebar.cdget.com/ko/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/이 페이지에서는 VitePress Sidebar 모듈의 설치 및 사용 방법을 안내합니다.
먼저 이 모듈을 사용하기 전에 VitePress 모듈을 사전 구성해야 할 수 있습니다.
Node.js 버전은 18.x 이상을 사용하는 것이 좋습니다. VitePress Sidebar는 ESM으로 작성되었습니다. CommonJS 환경에서 사용하려면 여기 지침을 참조하세요.
NPM 또는 다른 노드 모듈 패키지 관리자를 사용하여 모듈을 설치할 수 있습니다. 이 패키지는 개발자 환경에서만 사용되므로 devDependencies에 설치해야 합니다. 아래 명령어로 설치하세요:
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebarVitePress Sidebar의 generateSidebar 메서드를 사용하여 사이드바를 자동으로 생성할 수 있습니다.
지정된 루트 경로(documentRootPath)에 대해 폴더를 검색하고 VitePress에서 마크다운 파일을 작성하기 전에 찾은 다음 폴더 트리 구조에 따라 생성된 메뉴를 반환합니다.
먼저 아래 두 가지 방법 중 하나로 vitepress-sidebar를 import합니다.
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};VitePress의 구성 파일인 .vitepress/config.js 파일의 themeConfig.sidebar 속성에서 generateSidebar 메서드를 사용합니다. VitePress의 구성 파일은 프로젝트 설정에 따라 파일 이름이나 확장자가 다를 수 있습니다.
이것이 어떻게 출력되는지 테스트하려면 debugPrint 옵션을 true로 설정하여 VitePress를 빌드해 보세요. 콘솔에 출력이 표시될 것입니다.
generateSidebar의 설정에 대한 자세한 내용은 아래 API 섹션을 참조하세요.
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * For detailed instructions, see the links below:
+ * https://vitepress-sidebar.cdget.com/ko/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/VitePress Sidebar는 번거로운 작업 없이 한번의 설정만으로 사이드바 메뉴를 자동으로 생성하는 VitePress 플러그인입니다. 수많은 문서에 대한 분류를 손쉽게 만들어 시간을 절약하세요.
VitePress Sidebar는 다양한 프로젝트 환경에서 활용되고 있습니다.
VitePress Sidebar는 번거로운 작업 없이 한번의 설정만으로 사이드바 메뉴를 자동으로 생성하는 VitePress 플러그인입니다. 수많은 문서에 대한 분류를 손쉽게 만들어 시간을 절약하세요.
VitePress Sidebar는 다양한 프로젝트 환경에서 활용되고 있습니다.
CommonJS: ERR_REQUIRE_ESM vitepress-sidebar는 ESM 모듈입니다. 프로젝트에서 CJS를 사용하는 경우 ESM 모듈로 변환해야 합니다.
ESM 모듈에 대한 자세한 내용은 아래를 참조하세요: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
이러한 문제를 해결하기 위한 몇 가지 해결책이 아래에 나와 있습니다:
CJS 프로젝트에 사용하려는 경우 파일 확장자를 .js에서 .mjs로 변경한 후 다시 시도하세요. 특정 파일에 모듈 스크립트를 사용하도록 정의할 수 있습니다.
package.json 파일에 "type": "module" 줄을 추가합니다. 이 경우 프로젝트를 ESM 프로젝트로 변환해야 할 수도 있습니다.
{
+ name: 'docs',
+ type: 'module', // <-- 이 부분을 추가하세요.
+ version: '1.0.0',
+ scripts: {
+ dev: 'vitepress dev src',
+ build: 'vitepress build src',
+ serve: 'vitepress serve src'
+ }
+}CommonJS: ERR_REQUIRE_ESM vitepress-sidebar는 ESM 모듈입니다. 프로젝트에서 CJS를 사용하는 경우 ESM 모듈로 변환해야 합니다.
ESM 모듈에 대한 자세한 내용은 아래를 참조하세요: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
이러한 문제를 해결하기 위한 몇 가지 해결책이 아래에 나와 있습니다:
CJS 프로젝트에 사용하려는 경우 파일 확장자를 .js에서 .mjs로 변경한 후 다시 시도하세요. 특정 파일에 모듈 스크립트를 사용하도록 정의할 수 있습니다.
package.json 파일에 "type": "module" 줄을 추가합니다. 이 경우 프로젝트를 ESM 프로젝트로 변환해야 할 수도 있습니다.
{
+ name: 'docs',
+ type: 'module', // <-- 이 부분을 추가하세요.
+ version: '1.0.0',
+ scripts: {
+ dev: 'vitepress dev src',
+ build: 'vitepress build src',
+ serve: 'vitepress serve src'
+ }
+}CommonJS: 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:
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.
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'
+ }
+}CommonJS: 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:
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.
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'
+ }
+}在多层侧边栏中，菜单显示时每层都会缩进。不过，VitePress 默认从第二层开始缩进。例如
上面,directory-level-2是directory-level-1的子文件,但看起来处于相同的层级。
这不是VitePress侧边栏的问题,要解决这个问题,您需要通过**VitePress的自定义CSS**自定义现有主题的样式。
在.vitepress目录下创建一个theme目录,以覆盖现有样式所需的样式。然后在theme目录下创建一个index.js文件(如果您使用的是Typescript,请使用index.ts而不是index.js)和一个custom.css文件。
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...然后在 index.js 文件中添加以下内容：
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;接下来，在 custom.css 文件中添加以下内容：
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}现在启动 VitePress 服务器。这样就能更容易地看到子内容所在组的第一级层次结构。
需要注意的是,这里看到的垂直分隔线只是用CSS创建的;它应该创建为一个带有CSS类名为indicator的div,所以你应该知道,当你以后创建动态页面时,垂直分隔线可能不会被选中。
在多层侧边栏中，菜单显示时每层都会缩进。不过，VitePress 默认从第二层开始缩进。例如
上面,directory-level-2是directory-level-1的子文件,但看起来处于相同的层级。
这不是VitePress侧边栏的问题,要解决这个问题,您需要通过**VitePress的自定义CSS**自定义现有主题的样式。
在.vitepress目录下创建一个theme目录,以覆盖现有样式所需的样式。然后在theme目录下创建一个index.js文件(如果您使用的是Typescript,请使用index.ts而不是index.js)和一个custom.css文件。
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...然后在 index.js 文件中添加以下内容：
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;接下来，在 custom.css 文件中添加以下内容：
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}现在启动 VitePress 服务器。这样就能更容易地看到子内容所在组的第一级层次结构。
需要注意的是,这里看到的垂直分隔线只是用CSS创建的;它应该创建为一个带有CSS类名为indicator的div,所以你应该知道,当你以后创建动态页面时,垂直分隔线可能不会被选中。
多侧边栏是一项允许根据特定 URI 路径显示不同侧边栏菜单的功能。
只需在 vitepress-sidebar 中进行一些简单设置，就能轻松实现这一功能。最终，VitePress将按照预期输出选项。
要先了解有关多侧边栏的更多信息，我们建议您查看下面VitePress 的官方文档：
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
首先，假设你有一个名为 docs 的根项目，其中有名为 guide 和 config 的子目录，就像这样：
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md当URL位于/guide页面时,用户希望菜单仅显示guide的子菜单,隐藏config的子菜单。同样,当guide位于/config页面时,您希望隐藏guide的子菜单。
要在 vitepress-sidebar 中实现此功能,您需要采用与现有设置不同的方法。
像以前一样使用generateSidebar函数,但传递一个数组。该数组至少包含一个来自vitepress-sidebar的选项。数组中的值可以是任意数量的URL。当然,您也可以使用不同的设置进行配置。
// 必须传递数组参数!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);这些选项的值在结果中的使用情况如下：
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}下面是上述设置的输出示例：
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}以下选项可用于多个侧边栏:scanStartPath、basePath和resolvePath。每个选项都是可选的,但应根据具体情况正确使用。
下文将对每个选项进行说明。但我们建议您首先参考API页面上对每个选项的描述。
以下描述基于以下示例：
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath 此选项用于为不同的路由规则指定不同的根目录。documentRootPath是实际要扫描的根目录(即.vitepress目录所在的位置),而scanStartPath是此路由规则中实际要显示的根目录。
例如,若要仅包含/guide目录中的文件,请将scanStartPath的值指定为guide。但是,documentRootPath中的路径不应包含在内。
resolvePath VitePress使用此选项在遇到特定URI时显示相关菜单。例如,如果您想在到达example.com/guide/api时仅显示guide/api目录的内容,则resolvePath的值为/guide/api。建议您在路径前添加/。
通常,它的值与 scanStartPath 类似,但有时您可能需要为 i18n 路由指定不同的值。
basePath 此选项主要用于VitePress的重写规则,否则为可选。
它取代了VitePress中base路径的值。如果未指定该值,则指定resolvePath的值或根路径(/)。
如果目录的实际路径与URI中的路径结构不同,您应该能够通过重写功能导航到页面。通常情况下,侧边栏会根据根目录生成路径,而不会引用VitePress中的重写路径。
例如,假设您有一个重写规则,如下所示:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});guide/one.md 文档显示在 help/one 的路径中。但是,如果您这样做,侧边栏将不会显示菜单,因为它会尝试找到 help/one,而这是路径本身。
要解决这个问题,请将basePath中的路径改为help:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- Add this
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});上面的例子通常是在路径按步骤定义的情况下，但当你想显示按步骤深入的文件夹时，特别是当 URI 较短或使用与实际文件夹路径不同的约定时，你需要使用额外的方法。例如，你有一个这样的文件夹结构：
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md这次,我们希望当到达单级 URI /api 时,在 docs/guide/api 中显示菜单。预期的菜单仅显示 api-one.md 和 api-two.md。
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);但是,如果您这样配置选项,将无法显示菜单,因为api目录是guide的子目录。VitePress无法检测到这一点,并会导航到一个不存在的文档。
要解决这个问题,您需要同时使用VitePress的路由功能,请参阅以下文章以获取说明:
https://vitepress.dev/guide/routing#route-rewrites
按照上面的示例,我们将把“重写rewritesVitePress的config.js文件中,该文件应位于themeConfig之外:
export default defineConfig({
+ /* [START] Add This */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] Add This */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});现在，当 URI 路径以 /api 开头时，将显示 docs/guide/api 的子菜单！
多侧边栏是一项允许根据特定 URI 路径显示不同侧边栏菜单的功能。
只需在 vitepress-sidebar 中进行一些简单设置，就能轻松实现这一功能。最终，VitePress将按照预期输出选项。
要先了解有关多侧边栏的更多信息，我们建议您查看下面VitePress 的官方文档：
https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars
首先，假设你有一个名为 docs 的根项目，其中有名为 guide 和 config 的子目录，就像这样：
docs/
+├─ guide/
+│ ├─ index.md
+│ ├─ one.md
+│ ├─ two.md
+│ └─ do-not-include.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md当URL位于/guide页面时,用户希望菜单仅显示guide的子菜单,隐藏config的子菜单。同样,当guide位于/config页面时,您希望隐藏guide的子菜单。
要在 vitepress-sidebar 中实现此功能,您需要采用与现有设置不同的方法。
像以前一样使用generateSidebar函数,但传递一个数组。该数组至少包含一个来自vitepress-sidebar的选项。数组中的值可以是任意数量的URL。当然,您也可以使用不同的设置进行配置。
// 必须传递数组参数!!!!
+generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: '/guide/',
+ resolvePath: '/guide/',
+ useTitleFromFileHeading: true,
+ excludeFiles: ['do-not-include.md']
+ },
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'config',
+ resolvePath: '/config/',
+ useTitleFromFrontmatter: true
+ }
+]);这些选项的值在结果中的使用情况如下：
{
+ <resolvePath>: [
+ {
+ base: <basePath or resolvePath>,
+ items: [...] // \`<scanStartPath>/path/to/items\`
+ }
+ ]
+}下面是上述设置的输出示例：
{
+ '/guide/': {
+ base: '/guide/',
+ items: [
+ {
+ text: 'One',
+ link: 'one'
+ },
+ {
+ text: 'Two',
+ link: 'two'
+ }
+ ]
+ },
+ '/config/': {
+ base: '/config/',
+ items: [
+ {
+ text: 'Three',
+ link: 'three'
+ },
+ {
+ text: 'Four',
+ link: 'four'
+ }
+ ]
+ }
+}以下选项可用于多个侧边栏:scanStartPath、basePath和resolvePath。每个选项都是可选的,但应根据具体情况正确使用。
下文将对每个选项进行说明。但我们建议您首先参考API页面上对每个选项的描述。
以下描述基于以下示例：
docs/
+├─ .vitepress/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.mdscanStartPath 此选项用于为不同的路由规则指定不同的根目录。documentRootPath是实际要扫描的根目录(即.vitepress目录所在的位置),而scanStartPath是此路由规则中实际要显示的根目录。
例如,若要仅包含/guide目录中的文件,请将scanStartPath的值指定为guide。但是,documentRootPath中的路径不应包含在内。
resolvePath VitePress使用此选项在遇到特定URI时显示相关菜单。例如,如果您想在到达example.com/guide/api时仅显示guide/api目录的内容,则resolvePath的值为/guide/api。建议您在路径前添加/。
通常,它的值与 scanStartPath 类似,但有时您可能需要为 i18n 路由指定不同的值。
basePath 此选项主要用于VitePress的重写规则,否则为可选。
它取代了VitePress中base路径的值。如果未指定该值,则指定resolvePath的值或根路径(/)。
如果目录的实际路径与URI中的路径结构不同,您应该能够通过重写功能导航到页面。通常情况下,侧边栏会根据根目录生成路径,而不会引用VitePress中的重写路径。
例如,假设您有一个重写规则,如下所示:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});guide/one.md 文档显示在 help/one 的路径中。但是,如果您这样做,侧边栏将不会显示菜单,因为它会尝试找到 help/one,而这是路径本身。
要解决这个问题,请将basePath中的路径改为help:
export default defineConfig({
+ rewrites: {
+ 'guide/:page': 'help/:page'
+ },
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide',
+ basePath: 'help', // <---------------------- Add this
+ resolvePath: '/guide/'
+ }
+ ])
+ }
+});上面的例子通常是在路径按步骤定义的情况下，但当你想显示按步骤深入的文件夹时，特别是当 URI 较短或使用与实际文件夹路径不同的约定时，你需要使用额外的方法。例如，你有一个这样的文件夹结构：
docs/
+├─ guide/
+│ ├─ api/
+│ │ ├─ api-one.md
+│ │ └─ api-two.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ ├─ index.md
+ ├─ three.md
+ └─ four.md这次,我们希望当到达单级 URI /api 时,在 docs/guide/api 中显示菜单。预期的菜单仅显示 api-one.md 和 api-two.md。
generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+]);但是,如果您这样配置选项,将无法显示菜单,因为api目录是guide的子目录。VitePress无法检测到这一点,并会导航到一个不存在的文档。
要解决这个问题,您需要同时使用VitePress的路由功能,请参阅以下文章以获取说明:
https://vitepress.dev/guide/routing#route-rewrites
按照上面的示例,我们将把“重写rewritesVitePress的config.js文件中,该文件应位于themeConfig之外:
export default defineConfig({
+ /* [START] Add This */
+ rewrites: {
+ 'guide/api/:page': 'api/:page'
+ },
+ /* [END] Add This */
+ themeConfig: {
+ sidebar: generateSidebar([
+ {
+ documentRootPath: 'docs',
+ scanStartPath: 'guide/api',
+ resolvePath: '/api/'
+ }
+ ])
+ }
+});现在，当 URI 路径以 /api 开头时，将显示 docs/guide/api 的子菜单！
convertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading optionconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile options are defined together, try with title from index file when title is not fetched (#170)This version may cause unintended behavior. Please ignore this version.
convertSameNameSubFileToGroupIndexPage to get the name normally if subfile doesn't exist when setconvertSameNameSubFileToGroupIndexPage and useFolderTitleFromIndexFile are defined together (#170)Options type for TypeScript has been renamed to VitePressSidebarOptions.capitalizeEachWordsvitepress-sidebar.cdget.com!basePath optionrewrite and convertSameNameSubFileToGroupIndexPage option. (#146)index link when index.md file is shown (#147)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)5ed188e. do not warn 'use option together'removePrefixAfterOrdering option and the useTitleFrom option togetherremovePrefixAfterOrdering optionexcludeFilesByFrontmatter 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.prefixSeparator now accepts regular expressionssortMenusByFileDatePrefix optionremovePrefixAfterOrdering and prefixSeparator optionsortMenusOrderNumerically 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.sortMenusByFrontmatterDate optionsortMenusOrderNumericallyFromLink optionuseFolderLinkFromIndexFile, show the path to index.md togetherexcludeFilesByFrontmatter option (@aslafy-z)frontmatterOrderDefaultValue option (@aslafy-z)capitalizeEachWords optionsortMenusOrderNumerically optionuseIndexFileForFolderMenuInfo 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.folder/ instead of folder/index).rootGroupText, rootGroupLink, and rootGroupCollapsed options are available again. However, these options are no longer required.rootGroupText, rootGroupLink, and rootGroupCollapsed are not available in this version. Please update to the latest version. These options have been restored!useTitleFromFileHeading. If you do not want to remove Markdown syntax, set the keepMarkdownSyntaxFromTitle option to true.debugPrint optionkeepMarkdownSyntaxFromTitle optionsortMenusByFrontmatterOrder optionuseFolderLinkAsIndexPage option was renamed to useIndexFileForFolderMenuInfosortByFileName option was renamed to manualSortFileNameByPriorityuseFolderLinkAsIndexPage 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 fileuseFolderLinkAsIndexPage option, if the index file (index.md) does not exist, will display it without setting a link, replacing the name with the folder namesortMenusByName and sortMenusOrderByDescending optionsrootGroupCollapsed option not being applied correctlyincludeFolderIndexFile optionuseFolderLinkAsIndexPage option/null or undefined value for collapsed optionsrootGroupCollapsed 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.collapseDepthREADME.mdresolvePathroot option was renamed to documentRootPath.scanStartPath and resolvePath option. Please read README.md file.)folderLinkNotIncludesFileName optionwithIndex option was renamed to includeRootIndexFile.includeEmptyGroup option was renamed to includeEmptyFolder.excludeFiles optionexcludeFolders optionincludeDotFiles optionh1 tag and frontmatter correctlyconvertSameNameSubFileToGroupIndexPage and rename option not working togetherhyphenToSpace is now false.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.hyphenToSpace and underscoreToSpace options not being applied to directoriesrootGroupLink option.mocharc.json, remove tsconfig.prod.json file in .npmignoreuseTitleFromFrontmatter option. See README.md.useTitleFromFileHeading: Use only valid title values in titles that contain links1.0.0-alpha.44 breaking changes. See: https://vitepress.vuejs.org/config/theme-configscollapsed 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.includeEmptyGroup optioncapitalizeFirst bugcapitalizeFirst optionsortByFileName optioncollapseDepth option.editorconfig file and reformat codes (Development only)useTitleFromFileHeading option本页介绍 VitePress 侧边栏的所有选项。
| 解决路径问题 | 分组 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'文档文件所在的顶级路径。默认值为 /。
这是 .vitepress目录所在的路径，如果项目根目录中文档所在的文件夹是 /docs，则该选项的值应设为 docs 或 /docs。
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress 配置目录\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
用于扫描文档列表的根目录路径。在documentRootPath中设置的路径中的文件,在scanStartPath中设置的路径之外,不会被扫描。如果您指定了scanStartPath,建议您也设置documentRootPath,因为documentRootPath中设置的父路径应该出现在link中。
例如,如果根路径是/docs,要扫描的文件是/docs/sub-dir/scan-me,则设置如下:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (请勿包含 documentRootPath 的路径。)resolvePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
输入路径,为每个路径显示不同的侧边栏。路径前必须包含/。没有此值的选项将设置为根路径(/)。
例如: /, /path/sub-path, /guide/...
basePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
如果路径因VitePress的重写选项而改变,则可以使用此选项。它替换VitePress中的基本路径。如果此值不存在,则将使用来自resolvePath的值。
useTitleFromFileHeading booleanfalse如果值为 true，则显示带有 .md 文件中 h1 标题内容的标题。如果文件中不存在 h1 标题，则显示 Unknown。
默认菜单项按文件夹树顺序排序,因此如果您想按更改后的菜单名称重新排序,请将sortMenusByName选项设置为true。
useTitleFromFrontmatter booleanfalse如果值为true,则根据文件Frontmatter中title的值显示标题。如果无法解析该值,则如果useTitleFromFileHeading选项为true,则从h1标签中获取该值,如果失败,则从文件名中获取该值。
Frontmatter应位于文档顶部,并应如下所示(在 title: 值和标题之间需要留出空格)。
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitle根据文件中指定的Frontmatter中的键名显示菜单标题。如果指定的值在Frontmatter中不存在,将使用默认的title作为后备。
---\nname: This is frontmatter title value.\n---欲了解更多信息，请参阅以下文章： https://vitepress.dev/guide/frontmatter
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
useFolderTitleFromIndexFile booleanfalse如果该值为 true，则使用当前文件夹的 index.md 文件中的信息来获取菜单名称。如果不存在 index.md 文件，则使用文件夹名称。由于我们通常从 index.md 文件中获取 index 名称，因此建议同时使用 useTitleFromFileHeading 或 useTitleFromFrontmatter 选项，从该文件的 Markdown 标题或 Frontmatter 中获取标题。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，索引文件就会显示在菜单中。
useFolderLinkFromIndexFile booleanfalse如果此值为 true，将指定一个指向文件夹的链接，以便您可以导航到当前文件夹中的 index.md 文件。如果 index.md 文件不存在，则不会创建链接。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，则可在菜单中显示索引文件。
manualSortFileNameByPriority Array<string>[]按文件名（包括扩展名）数组的顺序排序。如果数组中没有与文件名匹配的值，排序优先级将被退回。这适用于文件和目录，同样的排列规则也适用于子目录。
sortMenusByName booleanfalse按名称对菜单项中的项目进行排序。通常情况下,文件夹扫描是按名称升序排序的,因此,如果不应用此选项,则应用默认排序,但如果使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则可能需要按名称重新排序,因为菜单名称已更改。此选项强制按名称排序,即使菜单名称已更改也是如此。
sortMenusByFileDatePrefix booleanfalse如果值为 true，则按菜单项名称中的日期前缀排序。日期格式必须是 YYYY-MM-DD 格式（例如 2024-01-01-menu-name, 2024-01-02.menu-name...）
要删除菜单文本中残留的日期前缀，可以使用 prefixSeparator 和 removePrefixAfterOrdering 选项。
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
sortMenusByFrontmatterOrder booleanfalse按 frontmatter 的 order 属性对菜单项排序。对于每个文件夹，按 order 属性的值（数字）升序排序，如果 sortMenusOrderByDescending 选项为 true，则按降序排序。如果 order 属性的值不是数字或不存在，则 order 会被判定为 0。
sortMenusByFrontmatterDate booleanfalse根据前端的date属性对菜单项进行排序。它还会按日期升序(如果sortMenusOrderByDescending为true,则按日期降序)对date属性值进行排序。日期格式必须符合YYYY-MM-DD或JavaScript Date数据类型。
sortMenusOrderByDescending booleanfalse如果此值为 true，则按降序排列菜单项中的项目。只有当 sortMenusByName 或 sortMenusByFrontmatterOrder 为 true时，才会启用此选项。
sortMenusOrderNumericallyFromTitle booleanfalse如果该值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。例如,如果您有名为1-a、10-a和2-a的文件,则常规排序将按名称排序,即['1-a', '10-a', '2-a']。这会导致菜单以非预期的顺序显示,因为10-a优先于2-a。
使用此选项,它们按以下顺序排序:['1-a', '2-a', '10-a']
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
sortMenusOrderNumericallyFromLink booleanfalse如果此值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。此选项与sortMenusOrderNumericallyFromTitle相同,但按链接而不是文件标题排序。因此,它不能与sortMenusOrderNumericallyFromTitle选项一起使用。
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
frontmatterOrderDefaultValue number0设置 frontmatter 的 order 属性未设置时的默认值。该选项仅在 sortMenusByFrontmatterOrder 为 true 时启用。
collapsed booleanfalse如果未指定collapsed选项(null 或 undefined),则不使用分组折叠/展开,所有菜单将一次性显示。如果为false,则创建菜单时所有分组都处于展开状态。如果为true,则创建菜单时所有分组都处于折叠状态。
(即使值为true,如果菜单位于折叠组中的文档中,也可能被展开。)
collapseDepth number1在指定的深度，菜单组会折叠。指定该选项后，组的折叠/展开将自动启用。顶层文件夹的深度为 1。
hyphenToSpace booleanfalse如果值为 true，文件名中的-符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
underscoreToSpace booleanfalse如果值为 true，文件名中的_符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
capitalizeFirst booleanfalse如果值为 true，菜单名称的第一个字母将强制为大写。当菜单名称通过 Markdown 标题或 frontmatter 导入时，该选项也会受到影响。
capitalizeEachWords booleanfalse如果值为 true，则单词的所有首字母大写，并用空格分隔。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
excludeFiles Array<string>[]与文件名(包括扩展名)相对应的文件不会显示在列表中。
excludeFilesByFrontmatterFieldName string|nullnull指定前缀字段名称为true的文档将从菜单中排除。
如果未指定选项或选项值未定义,则忽略该选项。
例如,如果选项值为exclude,则菜单中不会显示内容包含exclude: true的文档。
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContent根据选项的值,您可以使用其他名称,如draft、hide等,来代替exclude。
excludeFolders Array<string>[]列表中不显示与文件夹名称相对应的文件夹,也不显示文件夹中的任何子项。
includeDotFiles booleanfalse通常情况下,如果文件和文件夹名称前有句点(.),它们会被视为隐藏文件,不会在列表中显示。但是,如果此选项为true,则强制在列表中显示所有隐藏文件和文件夹。
includeEmptyFolder booleanfalse如果值为true,则还会显示不存在md文件的目录。
includeRootIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含顶级路径index.md文件。使用includeFolderIndexFile选项还可以包含子项目的索引文件。(如果文件不存在,则忽略它。)
includeFolderIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含文件夹路径index.md文件。使用includeRootIndexFile选项还可以包含根项目的索引文件。(如果文件不存在,则忽略它。)
removePrefixAfterOrdering booleanfalse从所有操作完成后显示的菜单项的每个菜单标题中删除特定的前缀。如果您想按文件名中的数字排序,而不使用前缀的排序,并且不希望该数字在菜单中显示,这是理想的选择。
例如,如果默认使用前缀分隔符(.),则以下菜单将重命名为
1.hello -> 菜单名:hello1.1.hello -> 菜单名:1.hello1-1.hello -> 菜单名:hello根据分隔符仅删除一次字母,因此子项(如1.1.)应使用1-1.。或者,您可以在前缀分隔符值上设置正则表达式来绕过它。
可与prefixSeparator选项一起使用。更多信息请参阅该选项的描述。
(注A:前缀仅影响标题,链接将使用文件链接的原始形式)。
(备注B:如果您使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则忽略此选项)。
prefixSeparator string|RegExp'.'此选项只能与 removePrefixAfterOrdering 选项结合使用以删除前缀。
从提取的菜单文本中删除指定数量字符（至少一个）的第一部分。例如，如果菜单名称为 1. Text，并且您将 prefixSeparator 值设置为 . ，则结果将仅为 Text。
您还可以使用正则表达式。与正则表达式匹配的值将被删除。例如，要删除 2024-01-01-hello 中字符串之前的日期，请将 prefixSeparator 值指定为 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g。结果为 hello。
rootGroupText string'Table of Contents'rootGroup 指定整个菜单组,而与目录结构无关。这将使用一个菜单步骤,因此您在使用时应格外小心。如果您不需要 rootGroup 选项,可以将其禁用。如果指定此值,则指定顶级菜单的名称。
rootGroupLink stringnull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。指定此值可指定指向 rootGroup 的链接。如果值为空，则不添加链接。
rootGroupCollapsed booleannull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。rootGroupCollapsed选项设置是否展开根组的子项。如果指定的默认值为 null 或 undefined，则不显示展开/折叠按钮。如果该值为 true，子项将以折叠方式显示；如果为 false，子项将以展开方式显示。
此选项仅适用于顶层项目。有关一般项目的折叠性，请参阅 collapsed 选项。
convertSameNameSubFileToGroupIndexPage booleanfalse如果此值为true,则当存在与文件夹同名的子文件时,将在文件夹中创建一个链接,用于导航至该文件,而该文件不会显示在子项中。
例如,如果您有一个文件夹,如下所示:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.md在 api 文件夹中添加了一个链接，而 api 文件夹中的 api 页面不包含在菜单列表中。点击文件夹中的链接会显示 api/api.md中的文件。
folderLinkNotIncludesFileName booleanfalse此选项仅在特殊情况下使用：当您有重写规则并且存在具有相同文件夹名称的子文件时，请将其与 convertSameNameSubFileToGroupIndexPage 选项并行使用。
如果此值为 true，则在建立文件夹链接时，忽略子项的存在，并仅将链接指定为文件夹路径。
例如，如果您有一个如下所示的文件夹：
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.md使用 convertSameNameSubFileToGroupIndexPage 选项，单击 guide/api 文件夹菜单将带您进入 guide/api/api，但如果您使用 folderLinkNotIncludesFileName 选项，则链接将为 guide/api/。
keepMarkdownSyntaxFromTitle booleanfalse如果此值为 true，则保留标题文本中包含的 Markdown 语法，而不删除它。通常会保留任何高亮或内联代码。无论是否使用此选项，超链接文本都会被移除。
debugPrint booleanfalse如果该值为true,则会将执行后创建的对象打印到控制台日志中。如果您配置了多个侧边栏,即使只包含其中一个选项,它也会输出所有侧边栏的结果。
本页介绍 VitePress 侧边栏的所有选项。
| 解决路径问题 | 分组 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'文档文件所在的顶级路径。默认值为 /。
这是 .vitepress目录所在的路径，如果项目根目录中文档所在的文件夹是 /docs，则该选项的值应设为 docs 或 /docs。
/\n├─ package.json\n├─ src/\n├─ docs/ <--------------- `documentRootPath` ('/docs')\n│ ├─ .vitepress/ <------ VitePress 配置目录\n│ ├─ another-directory/\n│ ├─ hello.md\n│ └─ index.md\n└─ ...scanStartPath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
用于扫描文档列表的根目录路径。在documentRootPath中设置的路径中的文件,在scanStartPath中设置的路径之外,不会被扫描。如果您指定了scanStartPath,建议您也设置documentRootPath,因为documentRootPath中设置的父路径应该出现在link中。
例如,如果根路径是/docs,要扫描的文件是/docs/sub-dir/scan-me,则设置如下:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (请勿包含 documentRootPath 的路径。)resolvePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
输入路径,为每个路径显示不同的侧边栏。路径前必须包含/。没有此值的选项将设置为根路径(/)。
例如: /, /path/sub-path, /guide/...
basePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
如果路径因VitePress的重写选项而改变,则可以使用此选项。它替换VitePress中的基本路径。如果此值不存在,则将使用来自resolvePath的值。
useTitleFromFileHeading booleanfalse如果值为 true，则显示带有 .md 文件中 h1 标题内容的标题。如果文件中不存在 h1 标题，则显示 Unknown。
默认菜单项按文件夹树顺序排序,因此如果您想按更改后的菜单名称重新排序,请将sortMenusByName选项设置为true。
useTitleFromFrontmatter booleanfalse如果值为true,则根据文件Frontmatter中title的值显示标题。如果无法解析该值,则如果useTitleFromFileHeading选项为true,则从h1标签中获取该值,如果失败,则从文件名中获取该值。
Frontmatter应位于文档顶部,并应如下所示(在 title: 值和标题之间需要留出空格)。
---\ntitle: Hello World\n---frontmatterTitleFieldName stringtitle根据文件中指定的Frontmatter中的键名显示菜单标题。如果指定的值在Frontmatter中不存在,将使用默认的title作为后备。
---\nname: This is frontmatter title value.\n---欲了解更多信息，请参阅以下文章： https://vitepress.dev/guide/frontmatter
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
useFolderTitleFromIndexFile booleanfalse如果该值为 true，则使用当前文件夹的 index.md 文件中的信息来获取菜单名称。如果不存在 index.md 文件，则使用文件夹名称。由于我们通常从 index.md 文件中获取 index 名称，因此建议同时使用 useTitleFromFileHeading 或 useTitleFromFrontmatter 选项，从该文件的 Markdown 标题或 Frontmatter 中获取标题。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，索引文件就会显示在菜单中。
useFolderLinkFromIndexFile booleanfalse如果此值为 true，将指定一个指向文件夹的链接，以便您可以导航到当前文件夹中的 index.md 文件。如果 index.md 文件不存在，则不会创建链接。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，则可在菜单中显示索引文件。
manualSortFileNameByPriority Array<string>[]按文件名（包括扩展名）数组的顺序排序。如果数组中没有与文件名匹配的值，排序优先级将被退回。这适用于文件和目录，同样的排列规则也适用于子目录。
sortMenusByName booleanfalse按名称对菜单项中的项目进行排序。通常情况下,文件夹扫描是按名称升序排序的,因此,如果不应用此选项,则应用默认排序,但如果使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则可能需要按名称重新排序,因为菜单名称已更改。此选项强制按名称排序,即使菜单名称已更改也是如此。
sortMenusByFileDatePrefix booleanfalse如果值为 true，则按菜单项名称中的日期前缀排序。日期格式必须是 YYYY-MM-DD 格式（例如 2024-01-01-menu-name, 2024-01-02.menu-name...）
要删除菜单文本中残留的日期前缀，可以使用 prefixSeparator 和 removePrefixAfterOrdering 选项。
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
sortMenusByFrontmatterOrder booleanfalse按 frontmatter 的 order 属性对菜单项排序。对于每个文件夹，按 order 属性的值（数字）升序排序，如果 sortMenusOrderByDescending 选项为 true，则按降序排序。如果 order 属性的值不是数字或不存在，则 order 会被判定为 0。
sortMenusByFrontmatterDate booleanfalse根据前端的date属性对菜单项进行排序。它还会按日期升序(如果sortMenusOrderByDescending为true,则按日期降序)对date属性值进行排序。日期格式必须符合YYYY-MM-DD或JavaScript Date数据类型。
sortMenusOrderByDescending booleanfalse如果此值为 true，则按降序排列菜单项中的项目。只有当 sortMenusByName 或 sortMenusByFrontmatterOrder 为 true时，才会启用此选项。
sortMenusOrderNumericallyFromTitle booleanfalse如果该值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。例如,如果您有名为1-a、10-a和2-a的文件,则常规排序将按名称排序,即['1-a', '10-a', '2-a']。这会导致菜单以非预期的顺序显示,因为10-a优先于2-a。
使用此选项,它们按以下顺序排序:['1-a', '2-a', '10-a']
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
sortMenusOrderNumericallyFromLink booleanfalse如果此值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。此选项与sortMenusOrderNumericallyFromTitle相同,但按链接而不是文件标题排序。因此,它不能与sortMenusOrderNumericallyFromTitle选项一起使用。
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
frontmatterOrderDefaultValue number0设置 frontmatter 的 order 属性未设置时的默认值。该选项仅在 sortMenusByFrontmatterOrder 为 true 时启用。
collapsed booleanfalse如果未指定collapsed选项(null 或 undefined),则不使用分组折叠/展开,所有菜单将一次性显示。如果为false,则创建菜单时所有分组都处于展开状态。如果为true,则创建菜单时所有分组都处于折叠状态。
(即使值为true,如果菜单位于折叠组中的文档中,也可能被展开。)
collapseDepth number1在指定的深度，菜单组会折叠。指定该选项后，组的折叠/展开将自动启用。顶层文件夹的深度为 1。
hyphenToSpace booleanfalse如果值为 true，文件名中的-符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
underscoreToSpace booleanfalse如果值为 true，文件名中的_符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
capitalizeFirst booleanfalse如果值为 true，菜单名称的第一个字母将强制为大写。当菜单名称通过 Markdown 标题或 frontmatter 导入时，该选项也会受到影响。
capitalizeEachWords booleanfalse如果值为 true，则单词的所有首字母大写，并用空格分隔。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
excludeFiles Array<string>[]与文件名(包括扩展名)相对应的文件不会显示在列表中。
excludeFilesByFrontmatterFieldName string|nullnull指定前缀字段名称为true的文档将从菜单中排除。
如果未指定选项或选项值未定义,则忽略该选项。
例如,如果选项值为exclude,则菜单中不会显示内容包含exclude: true的文档。
---\ntitle: This article is excluded.\nexclude: true\n---\n\n# Article\n\nContent根据选项的值,您可以使用其他名称,如draft、hide等,来代替exclude。
excludeFolders Array<string>[]列表中不显示与文件夹名称相对应的文件夹,也不显示文件夹中的任何子项。
includeDotFiles booleanfalse通常情况下,如果文件和文件夹名称前有句点(.),它们会被视为隐藏文件,不会在列表中显示。但是,如果此选项为true,则强制在列表中显示所有隐藏文件和文件夹。
includeEmptyFolder booleanfalse如果值为true,则还会显示不存在md文件的目录。
includeRootIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含顶级路径index.md文件。使用includeFolderIndexFile选项还可以包含子项目的索引文件。(如果文件不存在,则忽略它。)
includeFolderIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含文件夹路径index.md文件。使用includeRootIndexFile选项还可以包含根项目的索引文件。(如果文件不存在,则忽略它。)
removePrefixAfterOrdering booleanfalse从所有操作完成后显示的菜单项的每个菜单标题中删除特定的前缀。如果您想按文件名中的数字排序,而不使用前缀的排序,并且不希望该数字在菜单中显示,这是理想的选择。
例如,如果默认使用前缀分隔符(.),则以下菜单将重命名为
1.hello -> 菜单名:hello1.1.hello -> 菜单名:1.hello1-1.hello -> 菜单名:hello根据分隔符仅删除一次字母,因此子项(如1.1.)应使用1-1.。或者,您可以在前缀分隔符值上设置正则表达式来绕过它。
可与prefixSeparator选项一起使用。更多信息请参阅该选项的描述。
(注A:前缀仅影响标题,链接将使用文件链接的原始形式)。
(备注B:如果您使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则忽略此选项)。
prefixSeparator string|RegExp'.'此选项只能与 removePrefixAfterOrdering 选项结合使用以删除前缀。
从提取的菜单文本中删除指定数量字符（至少一个）的第一部分。例如，如果菜单名称为 1. Text，并且您将 prefixSeparator 值设置为 . ，则结果将仅为 Text。
您还可以使用正则表达式。与正则表达式匹配的值将被删除。例如，要删除 2024-01-01-hello 中字符串之前的日期，请将 prefixSeparator 值指定为 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g。结果为 hello。
rootGroupText string'Table of Contents'rootGroup 指定整个菜单组,而与目录结构无关。这将使用一个菜单步骤,因此您在使用时应格外小心。如果您不需要 rootGroup 选项,可以将其禁用。如果指定此值,则指定顶级菜单的名称。
rootGroupLink stringnull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。指定此值可指定指向 rootGroup 的链接。如果值为空，则不添加链接。
rootGroupCollapsed booleannull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。rootGroupCollapsed选项设置是否展开根组的子项。如果指定的默认值为 null 或 undefined，则不显示展开/折叠按钮。如果该值为 true，子项将以折叠方式显示；如果为 false，子项将以展开方式显示。
此选项仅适用于顶层项目。有关一般项目的折叠性，请参阅 collapsed 选项。
convertSameNameSubFileToGroupIndexPage booleanfalse如果此值为true,则当存在与文件夹同名的子文件时,将在文件夹中创建一个链接,用于导航至该文件,而该文件不会显示在子项中。
例如,如果您有一个文件夹,如下所示:
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.md在 api 文件夹中添加了一个链接，而 api 文件夹中的 api 页面不包含在菜单列表中。点击文件夹中的链接会显示 api/api.md中的文件。
folderLinkNotIncludesFileName booleanfalse此选项仅在特殊情况下使用：当您有重写规则并且存在具有相同文件夹名称的子文件时，请将其与 convertSameNameSubFileToGroupIndexPage 选项并行使用。
如果此值为 true，则在建立文件夹链接时，忽略子项的存在，并仅将链接指定为文件夹路径。
例如，如果您有一个如下所示的文件夹：
docs/\n├─ guide/\n│ ├─ api/\n│ │ └─ api.md\n│ ├─ one.md\n│ └─ two.md\n└─ config/\n └─ index.md使用 convertSameNameSubFileToGroupIndexPage 选项，单击 guide/api 文件夹菜单将带您进入 guide/api/api，但如果您使用 folderLinkNotIncludesFileName 选项，则链接将为 guide/api/。
keepMarkdownSyntaxFromTitle booleanfalse如果此值为 true，则保留标题文本中包含的 Markdown 语法，而不删除它。通常会保留任何高亮或内联代码。无论是否使用此选项，超链接文本都会被移除。
debugPrint booleanfalse如果该值为true,则会将执行后创建的对象打印到控制台日志中。如果您配置了多个侧边栏,即使只包含其中一个选项,它也会输出所有侧边栏的结果。
本页面将指导您安装和使用"VitePress Sidebar"模块。
首先，在使用本模块之前，您可能需要预先配置 VitePress。
我们建议使用 Node.js 18.x 或更高版本。VitePress Sidebar是用ESM编写的。要在 "CommonJS" 中使用它，请参见此处的说明。
您需要使用 NPM 或任何其他 Node 模块包管理器安装该模块。该软件包应安装在 devDependencies 中，因为它仅在开发人员环境中使用。使用下面的命令：
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebar您可以使用 VitePress Sidebar 的 generateSidebar 方法自动生成侧边栏。
该方法会根据给定的根路径（documentRootPath）扫描文件夹，在 VitePress 构建之前找到标记文件，并返回根据文件夹树结构生成的菜单。
首先，用以下两种方法之一导入 vitepress-sidebar 。
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};使用.vitepress/config.js文件中themeConfig.sidebar属性中的generateSidebar方法，该文件是VitePress的配置文件。VitePress 的配置文件可能有不同的文件名或扩展名，这取决于您的项目设置。
要测试输出结果如何，请尝试在将 debugPrint 选项设置为 true的情况下构建 VitePress。你应该能在控制台中看到输出结果。
有关generateSidebar配置的更多信息,请参阅下面的 API 部分。
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * 有关详细说明，请参阅下面的链接：
+ * https://vitepress-sidebar.cdget.com/zhHans/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/本页面将指导您安装和使用"VitePress Sidebar"模块。
首先，在使用本模块之前，您可能需要预先配置 VitePress。
我们建议使用 Node.js 18.x 或更高版本。VitePress Sidebar是用ESM编写的。要在 "CommonJS" 中使用它，请参见此处的说明。
您需要使用 NPM 或任何其他 Node 模块包管理器安装该模块。该软件包应安装在 devDependencies 中，因为它仅在开发人员环境中使用。使用下面的命令：
# via npm
+$ npm i -D vitepress-sidebar
+
+# via yarn
+$ yarn add -D vitepress-sidebar
+
+# via pnpm
+$ pnpm i -D vitepress-sidebar您可以使用 VitePress Sidebar 的 generateSidebar 方法自动生成侧边栏。
该方法会根据给定的根路径（documentRootPath）扫描文件夹，在 VitePress 构建之前找到标记文件，并返回根据文件夹树结构生成的菜单。
首先，用以下两种方法之一导入 vitepress-sidebar 。
import { generateSidebar } from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar(vitepressSidebarOptions)
+ }
+};import VitePressSidebar from 'vitepress-sidebar';
+
+const vitepressSidebarOptions = {
+ /* Options... */
+};
+
+export default {
+ themeConfig: {
+ sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions)
+ }
+};使用.vitepress/config.js文件中themeConfig.sidebar属性中的generateSidebar方法，该文件是VitePress的配置文件。VitePress 的配置文件可能有不同的文件名或扩展名，这取决于您的项目设置。
要测试输出结果如何，请尝试在将 debugPrint 选项设置为 true的情况下构建 VitePress。你应该能在控制台中看到输出结果。
有关generateSidebar配置的更多信息,请参阅下面的 API 部分。
import { generateSidebar } from 'vitepress-sidebar';
+
+export default {
+ themeConfig: {
+ sidebar: generateSidebar({
+ /*
+ * 有关详细说明，请参阅下面的链接：
+ * https://vitepress-sidebar.cdget.com/zhHans/guide/api
+ */
+ // documentRootPath: '/',
+ // scanStartPath: null,
+ // basePath: null,
+ // resolvePath: null,
+ // useTitleFromFileHeading: true,
+ // useTitleFromFrontmatter: true,
+ // frontmatterTitleFieldName: 'title',
+ // useFolderTitleFromIndexFile: false,
+ // useFolderLinkFromIndexFile: false,
+ // hyphenToSpace: true,
+ // underscoreToSpace: true,
+ // capitalizeFirst: false,
+ // capitalizeEachWords: false,
+ // collapsed: true,
+ // collapseDepth: 2,
+ // sortMenusByName: false,
+ // sortMenusByFrontmatterOrder: false,
+ // sortMenusByFrontmatterDate: false,
+ // sortMenusOrderByDescending: false,
+ // sortMenusOrderNumericallyFromTitle: false,
+ // sortMenusOrderNumericallyFromLink: false,
+ // frontmatterOrderDefaultValue: 0,
+ // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
+ // removePrefixAfterOrdering: false,
+ // prefixSeparator: '.',
+ // excludeFiles: ['first.md', 'secret.md'],
+ // excludeFilesByFrontmatterFieldName: 'exclude',
+ // 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,
+ })
+ }
+};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'
+ }
+];
+*/VitePress Sidebar是 VitePress 的一个插件,可通过简单的设置自动配置和管理页面的侧边栏。
VitePress侧边栏用于各种项目环境，包括我自己的网络服务。
',6)]))}const u=t(i,[["render",n]]);export{f as __pageData,u as default}; diff --git a/assets/zhHans_introduction.md.DfrRTf8r.lean.js b/assets/zhHans_introduction.md.DfrRTf8r.lean.js new file mode 100644 index 00000000..10fdf66d --- /dev/null +++ b/assets/zhHans_introduction.md.DfrRTf8r.lean.js @@ -0,0 +1 @@ +import{_ as t,c as r,a2 as a,o as s}from"./chunks/framework.Gf1jShja.js";const f=JSON.parse('{"title":"导言","description":"","frontmatter":{},"headers":[],"relativePath":"zhHans/introduction.md","filePath":"zhHans/introduction.md","lastUpdated":1725611780000}'),i={name:"zhHans/introduction.md"};function n(o,e,l,d,p,h){return s(),r("div",null,e[0]||(e[0]=[a('VitePress Sidebar是 VitePress 的一个插件,可通过简单的设置自动配置和管理页面的侧边栏。
VitePress侧边栏用于各种项目环境，包括我自己的网络服务。
',6)]))}const u=t(i,[["render",n]]);export{f as __pageData,u as default}; diff --git a/assets/zhHans_troubleshooting_err-require-esm.md.CUz0KWMD.js b/assets/zhHans_troubleshooting_err-require-esm.md.CUz0KWMD.js new file mode 100644 index 00000000..59788232 --- /dev/null +++ b/assets/zhHans_troubleshooting_err-require-esm.md.CUz0KWMD.js @@ -0,0 +1,10 @@ +import{_ as i,c as a,a2 as e,o as n}from"./chunks/framework.Gf1jShja.js";const d=JSON.parse('{"title":"CommonJS: ERR_REQUIRE_ESM","description":"","frontmatter":{"title":"CommonJS: ERR_REQUIRE_ESM"},"headers":[],"relativePath":"zhHans/troubleshooting/err-require-esm.md","filePath":"zhHans/troubleshooting/err-require-esm.md","lastUpdated":1725681781000}'),t={name:"zhHans/troubleshooting/err-require-esm.md"};function h(r,s,l,p,k,o){return n(),a("div",null,s[0]||(s[0]=[e(`CommonJS: ERR_REQUIRE_ESM vitepress-sidebar是一个ESM模块。如果您的项目使用CJS,则需要将其转换为ESM模块。
如需了解ESM模块的更多信息,请参阅以下内容:https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
为解决这些问题，有以下几种解决方案：
如果您想在 CJS 项目中使用该模块，请将文件扩展名从.js 改为 .mjs，然后再试一次。您可以为特定文件定义模块脚本。
在package.json文件中，添加"type"："module"行。这可能需要将项目转换为 ESM 项目。
{
+ name: 'docs',
+ type: 'module', // <-- 添加此内容
+ version: '1.0.0',
+ scripts: {
+ dev: 'vitepress dev src',
+ build: 'vitepress build src',
+ serve: 'vitepress serve src'
+ }
+}CommonJS: ERR_REQUIRE_ESM vitepress-sidebar是一个ESM模块。如果您的项目使用CJS,则需要将其转换为ESM模块。
如需了解ESM模块的更多信息,请参阅以下内容:https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
为解决这些问题，有以下几种解决方案：
如果您想在 CJS 项目中使用该模块，请将文件扩展名从.js 改为 .mjs，然后再试一次。您可以为特定文件定义模块脚本。
在package.json文件中，添加"type"："module"行。这可能需要将项目转换为 ESM 项目。
{
+ name: 'docs',
+ type: 'module', // <-- 添加此内容
+ version: '1.0.0',
+ scripts: {
+ dev: 'vitepress dev src',
+ build: 'vitepress build src',
+ serve: 'vitepress serve src'
+ }
+}This page describes all the options in the VitePress Sidebar.
| Resolving Paths | Grouping |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'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 string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
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 string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
Enter the path to the section to display a different sidebar for each path. The path must contain / before it. Options without this value will be set to the root section (/).
e.g. /, /path/sub-path, /guide/...
basePath string|nullnullThis option is used to configure multiple sidebars. You can learn more on the Multiple sidebars page.
This option can be utilized if the path has changed due to VitePress's rewrite option. It replaces the base path in VitePress. If this value does not exist, it will use the value from resolvePath instead.
useTitleFromFileHeading booleanfalseIf 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 booleanfalseIf 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: Hello World
+---frontmatterTitleFieldName stringtitleDisplays the menu title based on the key name in Frontmatter specified in the file. If the specified value does not exist in Frontmatter, the default title will be used as a fallback.
---
+name: 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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]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 booleanfalseSort 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 booleanfalseIf 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 booleanfalseSorts 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 booleanfalseSorts 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 sortMenusOrderByDescending option is true) The date format must match YYYY-MM-DD or the JavaScript Date data type.
sortMenusOrderByDescending booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 number0Sets the default value for the order property of the frontmatter when not set. This option is only enabled when sortMenusByFrontmatterOrder is true.
collapsed booleanfalseIf 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.
(Even if the value is true, the menu may be expanded if it is located in a document within a collapsed group.)
collapseDepth number1At 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 booleanfalseIf 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 Array<string>[]Files that correspond to an array of file names (including extensions) are not shown in the list.
excludeFilesByFrontmatterFieldName string|nullnullDocuments 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 Array<string>[]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 booleanfalseNormally, 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 booleanfalseIf the value is true, also displays directories where no md file exists as a group.
includeRootIndexFile booleanfalseIf 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 booleanfalseIf 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 booleanfalseRemoves 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:
1.hello -> Menu name: hello1.1.hello -> Menu name: 1.hello1-1.hello -> Menu name: helloRemoves 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 string|RegExp'.'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 string'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 stringnullFor 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 booleannullFor 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 booleanfalseIf 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.
For example, if you have a folder that looks like this:
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.mdA link is added to the api folder, and the api page in the api folder is not included in the menu listing. Clicking the link in the folder displays the file in api/api.md.
folderLinkNotIncludesFileName booleanfalseThis option is only used in special cases: when you have a rewrite rule and a subfile with the same folder name exists, use it in parallel with the convertSameNameSubFileToGroupIndexPage option.
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.
For example, if you have a folder that looks like this:
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.mdWith the convertSameNameSubFileToGroupIndexPage option, clicking on the guide/api folder menu will take you to guide/api/api, but if you use the folderLinkNotIncludesFileName option with it, the link will be guide/api/.
keepMarkdownSyntaxFromTitle booleanfalseIf 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 booleanfalseIf 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.
Powerful auto sidebar generator
A VitePress auto sidebar plugin that automatically creates a simple configuration
다중 사이드바에서는 메뉴가 각 계층마다 들여쓰기로 표시됩니다. 그러나 VitePress는 기본적으로 두 번째 계층부터 들여쓰기를 시작합니다. 예를 들어:
위의 directory-level-2는 directory-level-1의 하위 파일이지만 같은 계층 구조에 있는 것으로 보입니다.
이 문제는 VitePress 사이드바의 문제가 아니므로 이 문제를 해결하려면 VitePress의 사용자 정의 CSS 기능을 사용하여 기존 테마의 스타일을 사용자 정의해야 합니다.
.vitepress 디렉토리에 theme 디렉토리를 만들어 기존 스타일에 필요한 스타일을 재정의합니다. 그런 다음 theme 디렉토리 안에 index.js 파일(타입스크립트를 사용하는 경우 index.js 대신 index.ts를 사용)과 custom.css 파일을 만듭니다.
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ 이 줄 추가
+│ │ ├─ custom.css <------------ 이 줄 추가
+│ │ └─ index.js <------------ 이 줄 추가
+│ ├─ example.md
+│ └─ index.md
+└─ ...그런 다음 index.js 파일에 다음을 추가합니다:
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;다음으로 custom.css 파일에 다음을 추가합니다:
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}이제 VitePress 서버를 시작합니다. 이렇게 하면 하위 콘텐츠가 존재하는 그룹의 첫 번째 레벨의 계층 구조를 더 쉽게 확인할 수 있습니다.
여기에서 보이는 세로선은 CSS로만 생성된 것으로, indicator라는 CSS 클래스가 있는 div로 생성되어야 하므로 향후 동적 페이지를 작성할 때 세로선이 선택되지 않을 수 있다는 점에 유의해야 합니다.
이 페이지에서는 VitePress Sidebar의 모든 옵션에 대해 설명합니다.
| 경로 해석 | 그룹핑 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'문서 파일이 위치한 최상위 경로입니다. 기본값은 /입니다.
이 옵션은 .vitepress 디렉터리가 있는 경로이며, 프로젝트 루트에서 문서가 있는 폴더가 /docs인 경우 이 옵션의 값을 docs 또는 /docs로 설정해야 합니다.
/
+├─ package.json
+├─ src/
+├─ docs/ <--------------- `documentRootPath` ('/docs')
+│ ├─ .vitepress/ <------ VitePress 설정 디렉토리
+│ ├─ another-directory/
+│ ├─ hello.md
+│ └─ index.md
+└─ ...scanStartPath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
문서 목록을 스캔할 루트 디렉터리 경로입니다. scanStartPath에 설정된 경로를 벗어난 documentRootPath에 설정된 경로에 있는 파일은 스캔되지 않습니다. documentRootPath에 설정된 상위 경로가 link에 표시되어야 하므로 scanStartPath를 지정하는 경우 documentRootPath도 함께 설정하는 것이 좋습니다.
예를 들어 루트 경로가 /docs이고 스캔할 문서가 /docs/sub-dir/scan-me인 경우, 설정은 다음과 같이 표시됩니다:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (documentRootPath 경로를 포함하지 마세요.)resolvePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
각 경로마다 다른 사이드바를 표시하려면 섹션의 경로를 입력합니다. 경로 앞에 /가 포함되어야 합니다. 이 값이 없는 옵션은 루트 섹션(/)으로 설정됩니다.
e.g. /, /path/sub-path, /guide/...
basePath string|nullnull이 옵션은 다중 사이드바를 구성하는 데 사용됩니다. 다중 사이드바 페이지에서 자세히 알아볼 수 있습니다.
이 옵션은 VitePress의 rewrites 옵션으로 인해 경로가 변경된 경우에 사용할 수 있습니다. VitePress의 기본 경로를 대체합니다. 이 값이 존재하지 않으면 resolvePath의 값을 대신 사용합니다.
useTitleFromFileHeading booleanfalse값이 true이면 .md 파일의 h1 제목 내용이 포함된 제목을 표시합니다. 파일에 h1 제목이 존재하지 않으면 Unknown으로 표시됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useTitleFromFrontmatter booleanfalse값이 true이면 파일의 Frontmatter에 있는 title 값에 따라 제목을 표시합니다. 이 값을 구문 분석할 수 없는 경우 useTitleFromFileHeading 옵션이 true인 경우 h1 태그에서, 실패하면 파일 이름에서 가져옵니다.
'제목'은 문서 상단에 위치해야 하며 다음과 같이 표시되어야 합니다(title: 값과 제목 사이에 공백이 필요합니다).
---
+title: Hello World
+---frontmatterTitleFieldName stringtitle파일에 지정된 Frontmatter에서 지정한 키 이름을 기준으로 메뉴 제목을 표시합니다. 지정한 값이 Frontmatter에 존재하지 않으면 기본 title이 대체로 사용됩니다.
---
+name: 이 것은 Frontmatter의 제목값입니다.
+---자세한 내용은 다음 문서를 참조하세요: https://vitepress.dev/guide/frontmatter
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
useFolderTitleFromIndexFile booleanfalse이 값이 true이면 현재 폴더의 index.md 파일에 있는 정보를 사용하여 메뉴 이름을 가져옵니다. 인덱스 파일이 존재하지 않으면 폴더 이름이 사용됩니다. 일반적으로 index라는 이름은 index.md 파일에서 가져오기 때문에 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 함께 사용하여 해당 파일의 마크다운 헤더 또는 프론트매터에서 제목을 가져오는 것이 좋습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
useFolderLinkFromIndexFile booleanfalse이 값이 true이면 현재 폴더에 있는 index.md 파일로 이동할 수 있도록 폴더에 대한 링크를 지정합니다. 인덱스 파일이 존재하지 않으면 링크가 생성되지 않습니다.
인덱스 파일은 사이드바 메뉴에서 숨겨져 있지만, 인덱스 파일은 includeFolderIndexFile 옵션이 true인 경우 메뉴에 표시될 수 있습니다.
manualSortFileNameByPriority Array<string>[]파일 이름(확장자 포함) 배열을 순서대로 정렬합니다. 배열에 파일 이름과 일치하는 값이 없으면 정렬 우선순위가 반송됩니다. 이는 파일과 디렉터리 모두에 적용되며 하위 디렉터리에도 동일한 정렬 규칙이 적용됩니다.
sortMenusByName booleanfalse메뉴 항목의 항목을 이름별로 정렬합니다. 일반적으로 폴더 스캔은 오름차순 이름 정렬로 이루어지므로 이 옵션을 적용하지 않고 기본 정렬이 적용되지만, useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 메뉴 이름이 변경되어 이름별로 다시 정렬해야 할 수 있습니다. 이 옵션은 변경된 메뉴 이름에 대해서도 이름별로 강제로 정렬합니다.
sortMenusByFileDatePrefix booleanfalse값이 true이면 메뉴 항목 이름의 날짜 접두사를 기준으로 정렬합니다. 날짜 형식은 YYYY-MM-DD 형식이어야 합니다(예: 2024-01-01-menu-name, 2024-01-02.menu-name...).
이후 메뉴 텍스트에 남아있는 날짜 접두사를 제거하려면 prefixSeparator 및 removePrefixAfterOrdering 옵션을 활용하면 됩니다.
기본 메뉴 항목은 폴더 트리 순서로 정렬되므로 변경된 메뉴 이름으로 다시 정렬하려면 sortMenusByName 옵션을 true로 설정합니다.
sortMenusByFrontmatterOrder booleanfalse앞부분의 order 속성을 기준으로 메뉴 항목을 정렬합니다. 각 폴더에 대해 order 속성의 값(숫자)을 오름차순으로 정렬하거나, sortMenusOrderByDescending 옵션이 true인 경우 내림차순으로 정렬합니다. order 값이 숫자가 아니거나 존재하지 않는 경우 order는 0으로 판단됩니다.
sortMenusByFrontmatterDate booleanfalse앞부분의 date 속성을 기준으로 메뉴 항목을 정렬합니다. 또한 date 속성 값을 가장 오래된 날짜 순으로 오름차순으로 정렬합니다(sortMenusOrderByDescending 옵션이 true인 경우 내림차순). 날짜 형식은 YYYY-MM-DD 또는 JavaScript 날짜 데이터 유형과 일치해야 합니다.
sortMenusOrderByDescending booleanfalse이 값이 true이면 메뉴 항목의 항목을 내림차순으로 정렬합니다. 이 옵션은 sortMenusByName 또는 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
sortMenusOrderNumericallyFromTitle booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 예를 들어 1-a, 10-a, 2-a라는 이름의 파일이 있는 경우 일반 정렬에서는 ['1-a', '10-a', '2-a']라는 이름으로 정렬됩니다. 이렇게 하면 10-a가 2-a보다 우선하기 때문에 메뉴가 의도하지 않은 순서로 표시됩니다.
이 옵션을 사용하면 다음과 같이 정렬됩니다: ['1-a', '2-a', '10-a']
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
sortMenusOrderNumericallyFromLink booleanfalse이 값이 true이면 메뉴 이름 앞에 숫자가 포함된 경우 이름이 아닌 낮은 숫자를 기준으로 정렬됩니다. 이 옵션은 sortMenusOrderNumericallyFromTitle과 동일하지만 파일 제목이 아닌 링크를 기준으로 정렬합니다. 따라서 sortMenusOrderNumericallyFromTitle 옵션과 함께 사용할 수 없습니다.
내림차순 정렬을 원할 경우 sortMenusOrderByDescending 옵션과 함께 사용해야 합니다.
frontmatterOrderDefaultValue number0설정되지 않은 경우 앞부분의 order 속성에 대한 기본값을 설정합니다. 이 옵션은 sortMenusByFrontmatterOrder가 true인 경우에만 활성화됩니다.
collapsed booleanfalsecollapsed 옵션을 지정하지 않으면(null 또는 정의되지 않음) 그룹 접기/확장이 사용되지 않고 모든 메뉴가 한꺼번에 표시됩니다. false이면 모든 그룹이 확장된 상태로 메뉴가 생성됩니다. true이면 모든 그룹이 접힌 상태로 메뉴가 생성됩니다.
(값이 true이더라도 메뉴가 접힌 그룹 내의 문서에 있는 경우 메뉴가 확장될 수 있습니다.)
collapseDepth number1지정된 깊이에서 메뉴 그룹이 축소됩니다. 이 옵션을 지정하면 그룹 축소/확장이 자동으로 활성화됩니다. 최상위 폴더의 깊이는 1입니다.
hyphenToSpace booleanfalse값이 true이면 파일 이름에 포함된 - 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
underscoreToSpace booleanfalse값이 true이면 파일 이름에 포함된 _ 기호가 공백으로 변환되어 제목으로 표시됩니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeFirst booleanfalse값이 true이면 메뉴 이름의 첫 글자가 강제로 대문자로 바뀝니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
capitalizeEachWords booleanfalse값이 true이면 공백으로 구분된 단어의 첫 글자를 모두 대문자로 표시합니다. 이 옵션은 메뉴 이름을 마크다운 머리글 또는 앞부분을 통해 가져올 때도 영향을 받습니다.
excludeFiles Array<string>[]파일 이름 배열(확장자 포함)에 해당하는 파일은 목록에 표시되지 않습니다.
excludeFilesByFrontmatterFieldName string|nullnull지정된 앞부분 필드 이름의 값이 true로 설정된 문서는 메뉴에서 제외됩니다.
옵션이 지정되지 않았거나 옵션 값이 정의되지 않은 경우 무시됩니다.
예를 들어 옵션 값이 exclude인 경우 콘텐츠에 exclude: true가 포함된 문서는 메뉴에 표시되지 않습니다.
---
+title: This article is excluded.
+exclude: true
+---
+
+# Article
+
+Content이 옵션의 값에 따라 exclude 대신 draft, hide 등과 같은 다른 이름을 사용할 수 있습니다.
excludeFolders Array<string>[]폴더 이름의 배열에 해당하는 폴더는 목록에 표시되지 않으며, 폴더 내의 하위 항목도 표시되지 않습니다.
includeDotFiles booleanfalse일반적으로 파일 및 폴더 이름 앞에 점(.)이 있으면 숨겨진 것으로 간주되어 목록에 표시되지 않습니다. 하지만 이 옵션이 true이면 모든 숨겨진 파일과 폴더가 목록에 강제로 표시됩니다.
includeEmptyFolder booleanfalse값이 true인 경우, md 파일이 그룹으로 존재하지 않는 디렉터리도 표시합니다.
includeRootIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 최상위 경로 index.md 파일도 포함합니다. includeFolderIndexFile 옵션을 사용하여 하위 항목의 인덱스 파일도 포함합니다. (파일이 존재하지 않으면 무시됩니다.)
includeFolderIndexFile booleanfalse값이 true인 경우 사이드바 메뉴에 폴더 경로 index.md 파일도 포함합니다. 루트 항목의 인덱스 파일도 포함하려면 includeRootIndexFile 옵션을 사용합니다. (파일이 존재하지 않으면 무시됩니다.)
removePrefixAfterOrdering booleanfalse모든 작업이 완료된 후에 표시되는 메뉴 항목에서 각 메뉴 제목의 특정 접두사를 제거합니다. 이 옵션은 앞부분의 정렬을 사용하지 않고 파일 이름의 숫자를 기준으로 정렬하고 메뉴에 해당 숫자를 표시하지 않으려는 경우에 이상적입니다.
예를 들어 prefixSeparator가 기본값(.)인 경우 다음 메뉴의 이름이 다음과 같이 변경됩니다:
1.hello -> 메뉴명: hello1.1.hello -> 메뉴명: 1.hello1-1.hello -> 메뉴명: hello구분 기호에 따라 문자를 한 번만 제거하므로 1.1.과 같은 하위 항목은 1-1.처럼 사용해야 합니다. 또는 prefixSeparator 값에 정규식을 설정하여 이 문제를 해결할 수 있습니다.
prefixSeparator 옵션과 함께 사용할 수 있습니다. 자세한 내용은 해당 옵션의 설명을 참조하세요.
(참고: 접두사는 제목에만 영향을 미치며, 링크는 파일 링크를 그대로 사용합니다).
(참고 B: 이 옵션은 useTitleFromFileHeading 또는 useTitleFromFrontmatter 옵션을 사용하는 경우 무시됩니다).
prefixSeparator string|RegExp'.'이 옵션은 접두사를 제거하기 위해 removePrefixAfterOrdering 옵션과 함께 사용할 때만 사용할 수 있습니다.
추출된 메뉴 텍스트에서 지정된 문자 수(하나 이상)의 첫 부분을 제거합니다. 예를 들어 메뉴 이름이 1. Text이고 prefixSeparator 값을 . '로 설정하면 결과는 Text`가 됩니다.
정규식을 사용할 수도 있습니다. 정규식과 일치하는 값은 제거됩니다. 예를 들어 2024-01-01-hello에서 문자열 앞의 날짜를 제거하려면 prefixSeparator 값을 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g로 지정합니다. 결과는 hello입니다.
rootGroupText string'Table of Contents'루트 그룹은 디렉토리 구조에 관계없이 메뉴의 전체 그룹을 지정합니다. 이 옵션은 하나의 메뉴 단계를 사용하므로 사용에 주의해야 하며, 필요하지 않은 경우 루트 그룹 옵션을 비활성화할 수 있습니다. 이 값을 지정하면 최상위 메뉴의 이름을 지정하는 것입니다.
rootGroupLink stringnull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. 이 값을 지정하면 루트 그룹에 대한 링크가 지정됩니다. 값이 비어 있으면 링크가 추가되지 않습니다.
rootGroupCollapsed booleannull루트 그룹에 대한 자세한 내용은 rootGroupText 옵션 설명을 참조하세요. rootGroupCollapsed 옵션은 루트 그룹의 하위 항목을 펼칠지 여부를 설정합니다. 기본값인 null 또는 정의되지 않음으로 지정하면 확장/축소 버튼이 표시되지 않습니다. 값이 true이면 하위 항목이 접힌 상태로 표시되고, false이면 확장됩니다.
이 옵션은 최상위 항목에만 적용됩니다. 일반적인 항목 축소 여부는 collapsed 옵션을 참조하세요.
convertSameNameSubFileToGroupIndexPage booleanfalse이 값이 true이면 폴더와 같은 이름의 하위 파일이 있는 경우 폴더에 해당 파일로 이동할 수 있는 링크가 생성되고 하위 항목에 해당 파일이 표시되지 않습니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.mdapi 폴더에 링크가 추가되며, api 폴더의 api 페이지는 메뉴 목록에 포함되지 않습니다. 폴더의 링크를 클릭하면 api/api.md에 파일이 표시됩니다.
folderLinkNotIncludesFileName booleanfalse이 옵션은 특별한 경우에만 사용됩니다. 다시 쓰기 규칙이 있고 폴더 이름이 같은 하위 파일이 있는 경우 convertSameNameSubFileToGroupIndexPage 옵션과 병렬로 사용합니다.
이 값이 true인 경우 폴더 링크를 설정할 때 하위 항목의 존재를 무시하고 링크를 폴더 경로로만 지정합니다.
예를 들어 다음과 같은 폴더가 있는 경우:
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.mdconvertSameNameSubFileToGroupIndexPage 옵션을 사용하면 guide/api 폴더 메뉴를 클릭하면 guide/api/로 이동하지만 folderLinkNotIncludesFileName 옵션을 함께 사용하면 guide/api/로 링크가 연결됩니다.
keepMarkdownSyntaxFromTitle booleanfalse이 값이 true이면 제목 텍스트에 포함된 마크다운 구문을 제거하지 않고 그대로 유지합니다. 일반적으로 강조 표시 또는 인라인 코드를 유지합니다. 하이퍼링크 텍스트는 이 옵션과 관계없이 제거됩니다.
debugPrint booleanfalse이 값이 true이면 실행 후 생성된 객체를 콘솔 로그에 출력합니다. 여러 사이드바를 구성한 경우 옵션 중 하나만 포함하더라도 모든 사이드바 결과를 출력합니다.
在多层侧边栏中，菜单显示时每层都会缩进。不过，VitePress 默认从第二层开始缩进。例如
上面,directory-level-2是directory-level-1的子文件,但看起来处于相同的层级。
这不是VitePress侧边栏的问题,要解决这个问题,您需要通过**VitePress的自定义CSS**自定义现有主题的样式。
在.vitepress目录下创建一个theme目录,以覆盖现有样式所需的样式。然后在theme目录下创建一个index.js文件(如果您使用的是Typescript,请使用index.ts而不是index.js)和一个custom.css文件。
/
+├─ package.json
+├─ src/
+├─ docs/
+│ ├─ .vitepress/
+│ │ └─ theme/ <------------ Add this
+│ │ ├─ custom.css <------------ Add this
+│ │ └─ index.js <------------ Add this
+│ ├─ example.md
+│ └─ index.md
+└─ ...然后在 index.js 文件中添加以下内容：
import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;接下来，在 custom.css 文件中添加以下内容：
.group:has([role='button']) .VPSidebarItem.level-0 .items {
+ padding-left: 16px !important;
+ border-left: 1px solid var(--vp-c-divider);
+ border-radius: 2px;
+ transition: background-color 0.25s;
+}现在启动 VitePress 服务器。这样就能更容易地看到子内容所在组的第一级层次结构。
需要注意的是,这里看到的垂直分隔线只是用CSS创建的;它应该创建为一个带有CSS类名为indicator的div,所以你应该知道,当你以后创建动态页面时,垂直分隔线可能不会被选中。
本页介绍 VitePress 侧边栏的所有选项。
| 解决路径问题 | 分组 |
|---|---|
| documentRootPath | collapsed |
| scanStartPath | collapseDepth |
| resolvePath | rootGroupText |
| basePath | rootGroupLink |
| rootGroupCollapsed |
documentRootPath string'/'文档文件所在的顶级路径。默认值为 /。
这是 .vitepress目录所在的路径，如果项目根目录中文档所在的文件夹是 /docs，则该选项的值应设为 docs 或 /docs。
/
+├─ package.json
+├─ src/
+├─ docs/ <--------------- `documentRootPath` ('/docs')
+│ ├─ .vitepress/ <------ VitePress 配置目录
+│ ├─ another-directory/
+│ ├─ hello.md
+│ └─ index.md
+└─ ...scanStartPath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
用于扫描文档列表的根目录路径。在documentRootPath中设置的路径中的文件,在scanStartPath中设置的路径之外,不会被扫描。如果您指定了scanStartPath,建议您也设置documentRootPath,因为documentRootPath中设置的父路径应该出现在link中。
例如,如果根路径是/docs,要扫描的文件是/docs/sub-dir/scan-me,则设置如下:
documentRootPath: /docs,scanStartPath: sub-dir/scan-me (请勿包含 documentRootPath 的路径。)resolvePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
输入路径,为每个路径显示不同的侧边栏。路径前必须包含/。没有此值的选项将设置为根路径(/)。
例如: /, /path/sub-path, /guide/...
basePath string|nullnull此选项用于配置多个侧边栏。您可以在 多个侧边栏 页面上了解更多信息。
如果路径因VitePress的重写选项而改变,则可以使用此选项。它替换VitePress中的基本路径。如果此值不存在,则将使用来自resolvePath的值。
useTitleFromFileHeading booleanfalse如果值为 true，则显示带有 .md 文件中 h1 标题内容的标题。如果文件中不存在 h1 标题，则显示 Unknown。
默认菜单项按文件夹树顺序排序,因此如果您想按更改后的菜单名称重新排序,请将sortMenusByName选项设置为true。
useTitleFromFrontmatter booleanfalse如果值为true,则根据文件Frontmatter中title的值显示标题。如果无法解析该值,则如果useTitleFromFileHeading选项为true,则从h1标签中获取该值,如果失败,则从文件名中获取该值。
Frontmatter应位于文档顶部,并应如下所示(在 title: 值和标题之间需要留出空格)。
---
+title: Hello World
+---frontmatterTitleFieldName stringtitle根据文件中指定的Frontmatter中的键名显示菜单标题。如果指定的值在Frontmatter中不存在,将使用默认的title作为后备。
---
+name: This is frontmatter title value.
+---欲了解更多信息，请参阅以下文章： https://vitepress.dev/guide/frontmatter
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
useFolderTitleFromIndexFile booleanfalse如果该值为 true，则使用当前文件夹的 index.md 文件中的信息来获取菜单名称。如果不存在 index.md 文件，则使用文件夹名称。由于我们通常从 index.md 文件中获取 index 名称，因此建议同时使用 useTitleFromFileHeading 或 useTitleFromFrontmatter 选项，从该文件的 Markdown 标题或 Frontmatter 中获取标题。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，索引文件就会显示在菜单中。
useFolderLinkFromIndexFile booleanfalse如果此值为 true，将指定一个指向文件夹的链接，以便您可以导航到当前文件夹中的 index.md 文件。如果 index.md 文件不存在，则不会创建链接。
侧边栏菜单会隐藏 index.md 文件，但如果 includeFolderIndexFile 选项为 true，则可在菜单中显示索引文件。
manualSortFileNameByPriority Array<string>[]按文件名（包括扩展名）数组的顺序排序。如果数组中没有与文件名匹配的值，排序优先级将被退回。这适用于文件和目录，同样的排列规则也适用于子目录。
sortMenusByName booleanfalse按名称对菜单项中的项目进行排序。通常情况下,文件夹扫描是按名称升序排序的,因此,如果不应用此选项,则应用默认排序,但如果使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则可能需要按名称重新排序,因为菜单名称已更改。此选项强制按名称排序,即使菜单名称已更改也是如此。
sortMenusByFileDatePrefix booleanfalse如果值为 true，则按菜单项名称中的日期前缀排序。日期格式必须是 YYYY-MM-DD 格式（例如 2024-01-01-menu-name, 2024-01-02.menu-name...）
要删除菜单文本中残留的日期前缀，可以使用 prefixSeparator 和 removePrefixAfterOrdering 选项。
默认菜单项是按文件夹树顺序排序的，因此如果想按更改后的菜单名称重新排序，请将 sortMenusByName 选项设置为 true。
sortMenusByFrontmatterOrder booleanfalse按 frontmatter 的 order 属性对菜单项排序。对于每个文件夹，按 order 属性的值（数字）升序排序，如果 sortMenusOrderByDescending 选项为 true，则按降序排序。如果 order 属性的值不是数字或不存在，则 order 会被判定为 0。
sortMenusByFrontmatterDate booleanfalse根据前端的date属性对菜单项进行排序。它还会按日期升序(如果sortMenusOrderByDescending为true,则按日期降序)对date属性值进行排序。日期格式必须符合YYYY-MM-DD或JavaScript Date数据类型。
sortMenusOrderByDescending booleanfalse如果此值为 true，则按降序排列菜单项中的项目。只有当 sortMenusByName 或 sortMenusByFrontmatterOrder 为 true时，才会启用此选项。
sortMenusOrderNumericallyFromTitle booleanfalse如果该值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。例如,如果您有名为1-a、10-a和2-a的文件,则常规排序将按名称排序,即['1-a', '10-a', '2-a']。这会导致菜单以非预期的顺序显示,因为10-a优先于2-a。
使用此选项,它们按以下顺序排序:['1-a', '2-a', '10-a']
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
sortMenusOrderNumericallyFromLink booleanfalse如果此值为true,则如果菜单名称以数字开头,则按数字而不是名称排序。此选项与sortMenusOrderNumericallyFromTitle相同,但按链接而不是文件标题排序。因此,它不能与sortMenusOrderNumericallyFromTitle选项一起使用。
如果您希望按降序排序,则应与sortMenusOrderByDescending选项一起使用。
frontmatterOrderDefaultValue number0设置 frontmatter 的 order 属性未设置时的默认值。该选项仅在 sortMenusByFrontmatterOrder 为 true 时启用。
collapsed booleanfalse如果未指定collapsed选项(null 或 undefined),则不使用分组折叠/展开,所有菜单将一次性显示。如果为false,则创建菜单时所有分组都处于展开状态。如果为true,则创建菜单时所有分组都处于折叠状态。
(即使值为true,如果菜单位于折叠组中的文档中,也可能被展开。)
collapseDepth number1在指定的深度，菜单组会折叠。指定该选项后，组的折叠/展开将自动启用。顶层文件夹的深度为 1。
hyphenToSpace booleanfalse如果值为 true，文件名中的-符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
underscoreToSpace booleanfalse如果值为 true，文件名中的_符号将转换为空格并显示为标题。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
capitalizeFirst booleanfalse如果值为 true，菜单名称的第一个字母将强制为大写。当菜单名称通过 Markdown 标题或 frontmatter 导入时，该选项也会受到影响。
capitalizeEachWords booleanfalse如果值为 true，则单词的所有首字母大写，并用空格分隔。通过 Markdown 标题或 frontmatter 导入菜单名称时，该选项也会受到影响。
excludeFiles Array<string>[]与文件名(包括扩展名)相对应的文件不会显示在列表中。
excludeFilesByFrontmatterFieldName string|nullnull指定前缀字段名称为true的文档将从菜单中排除。
如果未指定选项或选项值未定义,则忽略该选项。
例如,如果选项值为exclude,则菜单中不会显示内容包含exclude: true的文档。
---
+title: This article is excluded.
+exclude: true
+---
+
+# Article
+
+Content根据选项的值,您可以使用其他名称,如draft、hide等,来代替exclude。
excludeFolders Array<string>[]列表中不显示与文件夹名称相对应的文件夹,也不显示文件夹中的任何子项。
includeDotFiles booleanfalse通常情况下,如果文件和文件夹名称前有句点(.),它们会被视为隐藏文件,不会在列表中显示。但是,如果此选项为true,则强制在列表中显示所有隐藏文件和文件夹。
includeEmptyFolder booleanfalse如果值为true,则还会显示不存在md文件的目录。
includeRootIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含顶级路径index.md文件。使用includeFolderIndexFile选项还可以包含子项目的索引文件。(如果文件不存在,则忽略它。)
includeFolderIndexFile booleanfalse如果值为true,则还要在侧边栏菜单中包含文件夹路径index.md文件。使用includeRootIndexFile选项还可以包含根项目的索引文件。(如果文件不存在,则忽略它。)
removePrefixAfterOrdering booleanfalse从所有操作完成后显示的菜单项的每个菜单标题中删除特定的前缀。如果您想按文件名中的数字排序,而不使用前缀的排序,并且不希望该数字在菜单中显示,这是理想的选择。
例如,如果默认使用前缀分隔符(.),则以下菜单将重命名为
1.hello -> 菜单名:hello1.1.hello -> 菜单名:1.hello1-1.hello -> 菜单名:hello根据分隔符仅删除一次字母,因此子项(如1.1.)应使用1-1.。或者,您可以在前缀分隔符值上设置正则表达式来绕过它。
可与prefixSeparator选项一起使用。更多信息请参阅该选项的描述。
(注A:前缀仅影响标题,链接将使用文件链接的原始形式)。
(备注B:如果您使用useTitleFromFileHeading或useTitleFromFrontmatter选项,则忽略此选项)。
prefixSeparator string|RegExp'.'此选项只能与 removePrefixAfterOrdering 选项结合使用以删除前缀。
从提取的菜单文本中删除指定数量字符（至少一个）的第一部分。例如，如果菜单名称为 1. Text，并且您将 prefixSeparator 值设置为 . ，则结果将仅为 Text。
您还可以使用正则表达式。与正则表达式匹配的值将被删除。例如，要删除 2024-01-01-hello 中字符串之前的日期，请将 prefixSeparator 值指定为 /[0-9]{4}-[0-9]{2}-[0-9]{2}-/g。结果为 hello。
rootGroupText string'Table of Contents'rootGroup 指定整个菜单组,而与目录结构无关。这将使用一个菜单步骤,因此您在使用时应格外小心。如果您不需要 rootGroup 选项,可以将其禁用。如果指定此值,则指定顶级菜单的名称。
rootGroupLink stringnull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。指定此值可指定指向 rootGroup 的链接。如果值为空，则不添加链接。
rootGroupCollapsed booleannull有关 rootGroup 的更多信息，请参阅 rootGroupText 选项说明。rootGroupCollapsed选项设置是否展开根组的子项。如果指定的默认值为 null 或 undefined，则不显示展开/折叠按钮。如果该值为 true，子项将以折叠方式显示；如果为 false，子项将以展开方式显示。
此选项仅适用于顶层项目。有关一般项目的折叠性，请参阅 collapsed 选项。
convertSameNameSubFileToGroupIndexPage booleanfalse如果此值为true,则当存在与文件夹同名的子文件时,将在文件夹中创建一个链接,用于导航至该文件,而该文件不会显示在子项中。
例如,如果您有一个文件夹,如下所示:
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.md在 api 文件夹中添加了一个链接，而 api 文件夹中的 api 页面不包含在菜单列表中。点击文件夹中的链接会显示 api/api.md中的文件。
folderLinkNotIncludesFileName booleanfalse此选项仅在特殊情况下使用：当您有重写规则并且存在具有相同文件夹名称的子文件时，请将其与 convertSameNameSubFileToGroupIndexPage 选项并行使用。
如果此值为 true，则在建立文件夹链接时，忽略子项的存在，并仅将链接指定为文件夹路径。
例如，如果您有一个如下所示的文件夹：
docs/
+├─ guide/
+│ ├─ api/
+│ │ └─ api.md
+│ ├─ one.md
+│ └─ two.md
+└─ config/
+ └─ index.md使用 convertSameNameSubFileToGroupIndexPage 选项，单击 guide/api 文件夹菜单将带您进入 guide/api/api，但如果您使用 folderLinkNotIncludesFileName 选项，则链接将为 guide/api/。
keepMarkdownSyntaxFromTitle booleanfalse如果此值为 true，则保留标题文本中包含的 Markdown 语法，而不删除它。通常会保留任何高亮或内联代码。无论是否使用此选项，超链接文本都会被移除。
debugPrint booleanfalse如果该值为true,则会将执行后创建的对象打印到控制台日志中。如果您配置了多个侧边栏,即使只包含其中一个选项,它也会输出所有侧边栏的结果。