Using sidebar helpers

The sidebar helpers automatically generate VitePress sidebars from the documentation directory structure.

Markdown entries use the title defined in their front-matter. When no title is available, the file name is used as a fallback.

Directory names are converted to readable sidebar group titles by replacing - and _ characters with spaces and capitalizing each word.

generateSidebar

generateSidebar generates the sidebar entries for a single documentation section.

generateSidebar({
  rootDir: 'guide',
  baseUrl: '/guide'
})

Available options:

Option	Description
rootDir	Directory containing the Markdown documentation
baseUrl	Base URL used to generate sidebar links
index	Optional entry inserted at the beginning of the sidebar
exclude	Markdown files to exclude. Defaults to ['index.md']

Directories are converted to sidebar groups and Markdown files to sidebar entries.

generateSidebars

generateSidebars generates the complete VitePress sidebar configuration from the documentation root containing the .vitepress directory.

sidebar: generateSidebars({
  configUrl: import.meta.url
})

The documentation root is automatically resolved from the location of the VitePress configuration file, independently of the directory from which the build is started.

For example, with:

docs/
├── .vitepress/
├── guide/
└── about/

the helper automatically generates /guide/ and /about/ sidebar sections.

generatePackageSidebar

generatePackageSidebar is a convenience helper for package documentation.

generatePackageSidebar('common-core')

It follows the package conventions:

packages/<pkg>/
public/<pkg>-openapi.json

The package index is automatically added as the first sidebar entry. If an OpenAPI specification is available, the <pkg>-openapi entry is automatically enriched with the API operations generated by vitepress-openapi.

For example:

sidebar: {
  '/packages/common-core/': generatePackageSidebar('common-core'),
  '/packages/common-geospatial/': generatePackageSidebar('common-geospatial')
}

OpenAPI integration

addOpenApiSidebar can also be used directly to enrich an existing sidebar with operations from an OpenAPI specification.