Basic Setup

This guide will walk you through setting up the VitePress Versioning Plugin in your VitePress project.

Ensure All Links Are Relative

WARNING

This is extremely important! If you do not enforce relative links within your documentation project, versioned pages will not be able to link to each other!

If you have a project with many absolute links, consider writing a script to automate this.

Before setting up the plugin, you will need to ensure that all links in your markdown files are relative. This is because the plugin uses the relative path of the file to determine which version of the file to link to.

This means that you should not use absolute links, such as /guide/getting-started but instead reference files based on their relative position to the file you are linking from.

• For example, if a file is located at docs/guide/getting-started.md and you want to link to docs/guide/advanced-setup.md, you should use the following link: ./advanced-setup.md.

• For example, if a file is located at docs/guide/getting-started.md and you want to link to docs/help/faq.md, you should use the following link: ../help/faq.md.

Configuration Setup

Replace defineConfig in your .vitepress/config.mts with defineVersionedConfig, and you can add a versioning object to your config.

export default defineVersionedConfig({
  // ... your vitepress config.
  versioning: {
    latestVersion: "1.0.0",
  },
}, __dirname);

You can further configure this plugin by adding additional properties to the versioning object and within the themeConfig object. For a full list of configuration options, see the Configuration Reference

Using the Version Switcher Component

If you want to use a more advanced version switcher component, such as the one used on this website, you can import the VersionSwitcher component from the plugin, register it in your theme config, and then use it within your navbar.

WARNING

You will need to set themeConfig.versionSwitcher to false to hide the basic version switcher.

import { Theme } from 'vitepress';
import DefaultTheme from 'vitepress/theme'
import VersionSwitcher from 'vitepress-versioning-plugin/src/components/VersionSwitcher.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) { 
    app.component('VersionSwitcher', VersionSwitcher) 
  } 
} satisfies Theme;

Add it to your navbar:

themeConfig: {
  versionSwitcher: false,
  nav: [
    ...,
    { 
      component: 'VersionSwitcher', 
    }, 
  ]
}

Localization Setup

Whilst the plugin provides support for versioning, it automatically supports localization only for pages.

WARNING

Sidebars and navbars are not automatically localized across versions.

There are plans for a future release to provide a more streamlined solution for localized sidebars and navbars, however, this is an extremely complex problem that requires a lot of thought and consideration to provide a solution that works for everyone.

Providing translations and versions for sidebars and navbars is complex, there isn't a one-size-fits-all solution. However, the plugin provides a number of configuration options to help you manage this complexity.

Consider taking a look at the following implementations to help you develop a system which can help you have versioned and localized sidebars:

• Fabric Documentation
• This Documentation Site!