Versioning

[fimbault]

Is your feature request related to a problem? Please describe.
Related to documentation versioning

Describe the solution you'd like
A way to version a set of markdown documents

Describe alternatives you've considered
Similar to VuePress Plugin or Docusaurus2

[brc-dd]

Well there is another workaround. Move your old docs to a subdomain. Then you can write config like this:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    nav: [
      {
        text: 'v3 (stable)',
        items: [
          {
            text: 'v2 (legacy)',
            link: 'https://v2.vuejs.org/'
          }
        ]
      }
    ]
  }
})

It will be rendered like this:

[jcstein]

hi again @brc-dd - do you have recommended practices on moving old versions to subdomain? if you do, have you seen anyone do this on github pages? we're thinking of moving another docs site to vitepress, but this is the one remaining blocker

[DMiradakis]

+1 this would really be essential. I'm trying to think of how to build this in VitePress, but I'm not sure at the moment.

[drwpow]

I’m pretty sure this is just done with multiple sidebars. Just move your versioned docs to a subfolder with the version in them.

You can then add a link to the nav where a user selects the version, and on change, the correct sidebar will show.

[IMB11]

I've utilized multiple sidebars, a nav switcher etc. to create a versioning example that should suffice for most projects until proper versioning support is added.

You can view it here: https://github.com/IMB11/vitepress-versioning Now a plugin on NPM! https://www.npmjs.com/package/vitepress-versioning-plugin

Im unsure how to make it a library, or whether it's even worth being a library

[ciscoo]

Well there is another workaround. Move your old docs to a subdomain. Then you can write config like this:

I would not consider this a workaround primarily because it assumes you have a domain. For users that use GitHub Pages without a custom domain, it is not possible.

A workaround, in my opinion, is something that can be done purely within the constraints of VitePress. The approaches that @drwpow and @IMB11 provided I would consider workarounds.

[IMB11]

I actually ended up turned my example into a proper plugin/library: https://www.npmjs.com/package/vitepress-versioning-plugin

[ajiho]

I actually ended up turned my example into a proper plugin/library: https://www.npmjs.com/package/vitepress-versioning-plugin

Thank you for your work, but I think we need Vitepress official to implement it better. Your package seems to have a different version control effect from the one provided by docusaurus

[IMB11]

Well, working without an official plugin API is extremely difficult - there's some whacky stuff going on in that plugin that would be 10x easier if there was a standardized approach to plugins.

[ajiho]

@brc-dd Will version control functionality be introduced in the future? I have tried the version control feature of docusaurus and I think it would be a satisfactory answer. Can the Vitepress team migrate it?

[javierjulio]

I've been migrating ActiveAdmin's documentation to Vitepress. The setup, experience and the overall docs are just fantastic, thank you! ❤️ The one issue I've run into is we do need the capability or an alternative for versioning without requiring a subdomain. If Vitepress could support some way of doing documentation versioning, that would be great and helpful feature.

[aminnairi]

First of all, thank you for making Vitepress, very nice to work with.

I think at this point, we can all agree to say that Vitepress is mainly used for tech docs websites, and that a first-class support for versioning is expected from such a tool.

And it would be especially useful for those, like me, that host their docs on a GitHub Pages, which does not play well with subdomains for old versions of the documentation, but again this would be a great added value to have a baked-in solution.

[koebi]

We are currently implementing versioning into our documentation, using the plugin by @IMB11, which is working quite nicely. We also host on GitHub Pages, so the above applies as well.

In particular, there are a few workarounds and drawbacks to our solution:

• documentation is duplicated for each version instead of being read from git tags or similar.
• directly switching from one version of a file to another isn't supported ootb
• the Search doesn't search only within the version, but either across all versions or only on the latest

These would (hopefully) go away if versioning becomes a first-class feature in vitepress - we're very much looking forward to that :)

[hamishwillee]

I haven't got this working yet, but I would also very much like to have a feature "like" this (this may not work for me, because versions are separately built and managed on my system).

Currently my switcher just displays "Versions", which is poor UX because users can't tell what version they are on. To give them this information I have had to hack the site title to display my current version.

A component to display the selected version in the navbar based on the current URL path of a page would be nice "minimal implementation".

FWIW easily the smartest implementation of this kind of thing I have seen is the gitbook legacy version switcher.
The magic in it was that the version structure defined in the config included a github URL to a master version of the config. The config for builds always fetches the latest version at that location. In other words the versions only had to be maintained in one place.

So something like this:

        "versions": {
            "gitbookConfigURL": "https://raw.githubusercontent.com/PX4/px4_user_guide/main/book.json",
            "options": [
                {
                    "value": "https://docs.px4.io/main/en/",
                    "text": "main"
                },
                {
                    "value": "https://docs.px4.io/v1.15/en/",
                    "text": "v1.15 - stable"
                },
                {
                    "value": "https://docs.px4.io/v1.14/en/",
                    "text": "v1.14"
                },
            ]
        }