diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e890c85..178f4e8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -58,14 +58,38 @@ jobs:
     if: github.event_name == 'release'
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: main
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: "https://registry.npmjs.org/"
-      - uses: pnpm/action-setup@v4
-      - run: pnpm install
-      - name: Build docs
+          cache: "pnpm"
+      - name: Install dependencies (main branch)
+        run: pnpm install
+      - name: Build v2 docs from main branch
         run: pnpm docs:build
+      - name: Move v2 docs to combined folder
+        run: |
+          mkdir -p combined/v2
+          mv docs/.vitepress/dist/* combined/v2/
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          clean: false
+      - name: Install dependencies (release tag)
+        run: pnpm install
+      - name: Build and move v3 docs if v3 release
+        run: |
+          TAG_NAME="${{ github.ref_name }}"
+          if [[ "$TAG_NAME" == v3* ]]; then
+            pnpm docs:build
+            mkdir -p combined/v3
+            mv docs/.vitepress/dist/* combined/v3/
+          fi
+      - name: Copy v2 docs to root for default access
+        run: cp -r combined/v2/* combined/
       - name: Deploy docs to production server
         uses: easingthemes/ssh-deploy@main
         env:
@@ -73,5 +97,5 @@ jobs:
           REMOTE_HOST: ${{ secrets.SSH_HOST }}
           REMOTE_USER: ${{ secrets.SSH_USER }}
           REMOTE_PORT: ${{ secrets.SSH_PORT }}
-          SOURCE: "docs/.vitepress/dist/."
+          SOURCE: "combined/."
           TARGET: ${{ secrets.TARGET_DIR_DOCS }}
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 0fabc31..5eb44a4 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -1,19 +1,31 @@
 import { defineConfig } from "vitepress";
- // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- avoiding error when developing the docs locally
- // @ts-ignore: linting before typedoc is generated will throw an error here
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment -- avoiding error when developing the docs locally
+// @ts-ignore: linting before typedoc is generated will throw an error here
 import typedocSidebar from "../api/typedoc-sidebar.json";
+import { fullVersion, majorVersion, majorNumber } from "./version";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: "@tmlmt/cooklang-parser",
   description: "Documentation for the npm package @tmlmt/cooklang-parser",
+  base: `/${majorVersion}/`,
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: "Home", link: "/" },
-      { text: "Guide", link: "/guide-cooklang-specs"},
+      { text: "Guide", link: "/guide-cooklang-specs" },
       { text: "API", link: "/api/classes/Recipe" },
       { text: "Examples", link: "/examples-scaling-recipes" },
+      {
+        text: fullVersion,
+        items: [
+          { text: fullVersion, link: "/" },
+          {
+            text: majorNumber === 2 ? "v3" : "v2",
+            link: majorNumber === 2 ? "../v3/" : "../v2/",
+          },
+        ],
+      },
     ],
 
     sidebar: [
diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue
new file mode 100644
index 0000000..2e97502
--- /dev/null
+++ b/docs/.vitepress/theme/Layout.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import DefaultTheme from "vitepress/theme";
+import { isPrerelease, majorVersion } from "../version";
+
+const { Layout } = DefaultTheme;
+</script>
+
+<template>
+  <Layout>
+    <template #layout-top>
+      <div v-if="isPrerelease" class="prerelease-banner top-banner">
+        ⚠️ This is pre-release documentation for {{ majorVersion }}. For stable docs,
+        visit <a href="../v2/">v2</a>.
+      </div>
+      <component v-if="isPrerelease" :is="'style'">
+        :root { --vp-layout-top-height: 37px; }
+        .VPHome { margin-bottom: 96px !important; }
+      </component>
+    </template>
+  </Layout>
+</template>
+
+<style scoped>
+.prerelease-banner.top-banner {
+  background: #fff3cd;
+  border-bottom: 1px solid #ffc107;
+  color: #856404;
+  padding: 0.5rem 1rem;
+  text-align: center;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 50;
+}
+
+.prerelease-banner a {
+  color: #533f03;
+  font-weight: 600;
+  text-decoration: underline;
+}
+
+.prerelease-banner a:hover {
+  color: #1a1400;
+}
+</style>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 0000000..35a2be1
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,9 @@
+import DefaultTheme from "vitepress/theme";
+import type { DefineComponent } from "vue";
+import Layout from "./Layout.vue";
+import type { Theme } from "vitepress";
+
+export default {
+  extends: DefaultTheme,
+  Layout: Layout as DefineComponent,
+} satisfies Theme;
diff --git a/docs/.vitepress/version.ts b/docs/.vitepress/version.ts
new file mode 100644
index 0000000..126fc0b
--- /dev/null
+++ b/docs/.vitepress/version.ts
@@ -0,0 +1,15 @@
+import pkg from "../../package.json";
+
+const version = pkg.version;
+
+/** Full version string with 'v' prefix, e.g., "v2.1.7" or "v3.0.0-alpha.1" */
+export const fullVersion = `v${version}`;
+
+/** Major version with 'v' prefix, e.g., "v2" or "v3" */
+export const majorVersion = `v${version.split(".")[0]}`;
+
+/** Major version number, e.g., 2 or 3 */
+export const majorNumber = parseInt(version.split(".")[0], 10);
+
+/** True if this is a prerelease version (contains a hyphen, e.g., "3.0.0-alpha.1") */
+export const isPrerelease = version.includes("-");
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 5b2b7b2..e300107 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -22,7 +22,11 @@ export default defineConfig(
       },
       parserOptions: {
         projectService: {
-          allowDefaultProject: ["docs/.vitepress/config.mts"],
+          allowDefaultProject: [
+            "docs/.vitepress/config.mts",
+            "docs/.vitepress/*/*.ts",
+            "docs/.vitepress/*.ts",
+          ],
         },
         tsconfigRootDir: import.meta.dirname,
       },