Multi version docs support

[sanyuan0704]

Multi language overview

Currently, rspress supports multi language docs.That is to say:

1. You can write docs in multiple languages, such as the following file structure:

doc
├── en
│   ├── index.md
│   └── guide
│       ├── getting-started.md
│       └── introduction.md
└── zh
    ├── index.md
    └── guide
        ├── getting-started.md
        └── introduction.md

2. Rspress will automatically generate a language switcher in the navbar.

3. Rspress will automatically add the language prefix to the link in docs, such as /en/ or /zh/.But in default language, the prefix will not be added.

Multi version usage

1. File structure

But sometimes we also need multi version docs, such as the following file structure:

doc
├── v1
│   ├── index.md
│   └── guide
│       ├── getting-started.md
│       └── introduction.md
└── v2
    ├── index.md
    └── guide
        ├── getting-started.md
        └── introduction.md

Also, the multi version may be combined with multi language, such as the following file structure:

doc
├── v1
│   ├── en
│   │   ├── index.md
│   │   └── guide
│   │       ├── getting-started.md
│   │       └── introduction.md
│   └── zh
│       ├── index.md
│       └── guide
│           ├── getting-started.md
│           └── introduction.md
└── v2
    ├── en
    │   ├── index.md
    │   └── guide
    │       ├── getting-started.md
    │       └── introduction.md
    └── zh
        ├── index.md
        └── guide
            ├── getting-started.md
            └── introduction.md

2. Config

In the rspress.config.ts file, you can configure the multi version docs:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

The default parameter is the default version, and the versions parameter is the version list.

Then the user has integrated the multi version feature. The framework will do the following:

1. Automatically add the language prefix to the link in docs, such as /v1/ or /v2/.

2. For default version, the version prefix in path will not be added.

3. Provide useVersion hook to get the current version in custom components in docs.

Implement

The implement will include the following parts:

• RouteService, which is responsible for generating the convential routes and the routes for multi version.

• Links Rewrite. For the links in md(x) file, we need to rewrite them to the convential routes or the routes for multi version, for example, /guide/getting-started.md will be rewrited to /v1/guide/getting-started.md.The rewrite process is implement by usePathUtils hook in runtime.

Maybe you could ask the question: why not rewrite the links in compile time? Taking account of that the mdx compiler includes two versions: in JS and in Rust.So if we implement the link rewrite in runtime, we will have no need to adapt the two versions of mdx compiler.

The implement pr is here.

In the Future

To support multi version docs, we can do more things in the future:

1. such more flexible versions config:

// current
multiVersion: {
  versions: ['v1', 'v2', 'v3'],
}

// we can also support
multiVersion: {
  versions: [
    {
      label: 'Frist Version',
      value: 'v1'
    },
    {
      label: 'Second Version',
      value: 'v2'
    },
    'v3'
  ],
}

2. Display the version switcher in the navbar as well as the language switcher.

If you have any ideas, please feel free to discuss or open a pr.