Setting up multiversion build

Here are some steps to:

• Build multiple versions of your docs
• Get a nice index page listing them
• Get some versioning docs in the sidebar
• Speed up builds with caching

There are what we do to set up the multiversion build for this site eg this is an example and YMMV.

1. Configuration

Start by setting up mvb in your themeConfig.

export default defineConfig({
  themeConfig:  {
    multiVersionBuild: {
      build: 'stable',
      match: 'v[0-9].*',
      base: '/v/',
      satisfies: '>=1.0.0-beta.42',
    },
  }
});

This will build the stable version of your docs into siteConfig.base. It will also build a version for each git tag that matches v[0-9].* and is above or equal to 1.0.0-beta.42 into the /v/ directory relative to your siteConfig.base eg /v/v1.0.0-beta.42.

You can get more info on the above options over here.

2. Build

You will want to update your build process from something like npx vitepress build docs to npx mvb docs. For example we modified our netlify.toml

[build]
  base = "./"
  publish = "docs/.vitepress/dist/"
  command = "vitepress build docs"
  command = "npx mvb docs"

You can get more detail on the mvb command over here.

You may also want to consider using the usual npx vitepress build docs in certain build contect eg pull requests that generate previews as that probably makes more sense for various reasons.

Here is what we do in our netlify.toml to separate between deploy-preview and all other build contexts.

[build]
  base = "./"
  publish = "docs/.vitepress/dist/"
  command = "npx mvb docs"

[context.deploy-preview]
  command = "npm run build"

3. Index

We've found it's good to put a version index.md at the root of themeConfig.multiVersionBuild.base. This is what ours looks like:

./v/index.md

---
description: All Other documentation versions
title: Docuverse
contributors: false
lastUpdated: false
editLink: false
next: false
---

# Docuverse

<br />
<br />

<div
  v-for="link in links"
  :key="link.text"
  class="version-link"
>
  <VPLVersionLink
    :text="link.text"
    :href="link.href"
    :prerelease="link.prerelease"
    :stable="link.stable"
    :edge="link.edge"
  />
</div>

<br />

<div>
  <VPLVersionLink :dev="true" :text="aliases.dev" :href="aliasLinks.dev" />
</div>

<script setup>
import {useTags} from '@lando/vitepress-theme-default-plus';
import {VPLCollectionPage, VPLCollectionPageSection, VPLCollectionPageTitle, VPLVersionLink} from '@lando/vitepress-theme-default-plus';

const {aliases, aliasLinks, links} = useTags();
</script>

Note that useTags() has additional exportables you can read more about here.

Also note that VPLVersionLink does not normalize :href to the site base which is by design to aid in navigating between versions.

4. Sidebar

We use the Sidebar Ender to put our version information and version index page in the sidebar.

Consider the following example:

import {createRequire} from 'module';
import {resolve, dirname} from 'node:path';
import {fileURLToPath} from 'node:url';
import {default as isDevRelease} from '@lando/vitepress-theme-default-plus/is-dev-release';

import {defineConfig} from '../../config';

const require = createRequire(import.meta.url);
const __dirname = dirname(resolve(fileURLToPath(import.meta.url)));

// get version info
const {version} = require('../../package.json');

const sidebarEnder = {
  text: `v${version}`,
  collapsed: true,
  items: [
    {
      text: 'Other Doc Versions',
      items: [
        {rel: 'mvb', text: 'stable', target: '_blank', link: '/v/stable/'},
        {rel: 'mvb', text: 'edge', target: '_blank', link: '/v/edge/'},
        {text: '<strong>see all versions</strong>', link: '/v/'},
      ],
    },
    {text: 'Other Releases', link: 'https://github.com/lando/vitepress-theme-default-plus/releases'},
  ],
};

// if version is a stable or edge release then add in the release notes
if (!isDevRelease(version)) {
  sidebarEnder.items.splice(1, 0, {
    text: 'Release Notes',
    link: `https://github.com/lando/vitepress-theme-default-plus/releases/tag/v${version}`,
  });
}

export default defineConfig({
  themeConfig:  {
    sidebarEnder,
  },
});

There are a few things above to note:

• isDevRelease can be imported from @lando/vitepress-theme-default-plus/is-dev-release and is helpful to generate different things based on the type of release. For example, we use it to add an extra "Release Notes" link for all non-developement releases.
• {rel: 'mvb'} is a special thing exclusive to this theme that will tell the theme to treat the links as absolute instead of as normalized to siteConfig.base. This is the same behavior as VPLVersionLink in #3 above and similarly is to help with navigating between the versions.
• You will want to use themeConfig.multiVersionBuild.base and wherever you put the index from #3 ⬆️ for your links.

5. Caching

By default successful builds will cache in ${siteConfig.cacheDir}/@lando/mvb.

However, if you are using an ephemeral build or testing environment a la GitHub Actions you may need to configure the cache to persist across rebuilds.

NETLIFY

If you are using Netlify to deploy your docs then caching will be configured and working by default!

For example we use @actions/cache to speed up our mvb test builds by caching docs/.vitepress/cache/@lando/mvb as in the below example:

uses: actions/cache@v4
with:
  key: lando-mvb
  path: docs/.vitepress/cache/@lando/mvb
  save-always: true