From 40a3af941fc14235539ee302e6af4b295caa704f Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Tue, 21 Jul 2026 19:14:00 -0700
Subject: [PATCH] add versionLabel to overrides

---
 dev/vite.config.mts                                           | 1 +
 docs/src/routes/guide/(2)config.mdx                           | 4 +++-
 .../reference/default-theme/components/version-selector.mdx   | 1 +
 src/config/index.ts                                           | 2 ++
 src/default-theme/components/VersionSelector.tsx              | 4 +++-
 tests/config/index.test.ts                                    | 2 +-
 tests/config/route-config.test.ts                             | 2 ++
 7 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/dev/vite.config.mts b/dev/vite.config.mts
index c202805..88f5035 100644
--- a/dev/vite.config.mts
+++ b/dev/vite.config.mts
@@ -112,6 +112,7 @@ export default defineConfig({
 				},
 				{
 					version: "v1",
+					versionLabel: "v1 (legacy)",
 					title: "SolidBase v1 Demo",
 					themeConfig: {
 						sidebar: {
diff --git a/docs/src/routes/guide/(2)config.mdx b/docs/src/routes/guide/(2)config.mdx
index 55a7349..8e8ef31 100644
--- a/docs/src/routes/guide/(2)config.mdx
+++ b/docs/src/routes/guide/(2)config.mdx
@@ -55,6 +55,7 @@ interface SolidBaseConfig<ThemeConfig> {
   robots?: boolean | RobotsConfig;
   lang?: string;
   locales?: Record<string, LocaleConfig<ThemeConfig>>;
+    versionLabel?: string;
   routes?: SolidBaseRoutesConfig;
   overrides?: Array<SolidBaseRouteOverride<ThemeConfig>>;
   themeConfig?: ThemeConfig;
@@ -170,12 +171,13 @@ overrides: [
     {
         project: "solidbase",
         version: "v1",
+        versionLabel: "v1 (legacy)",
     },
 ],
 // ..
 ```
 
-Route override selectors use route axis names. Override config is applied over the base config, and `themeConfig` is shallow-merged with the base `themeConfig`.
+Route override selectors use route axis names. Override config is applied over the base config, and `themeConfig` is shallow-merged with the base `themeConfig`. Use `versionLabel` to replace the active version selector label for a matching route without changing the version label shown elsewhere.
 
 #### Miscellaneous options
 
diff --git a/docs/src/routes/reference/default-theme/components/version-selector.mdx b/docs/src/routes/reference/default-theme/components/version-selector.mdx
index ba8e401..8174911 100644
--- a/docs/src/routes/reference/default-theme/components/version-selector.mdx
+++ b/docs/src/routes/reference/default-theme/components/version-selector.mdx
@@ -21,6 +21,7 @@ Version switcher for sites that configure `routes.version`.
 
 - omitted when fewer than two version options are available
 - uses Kobalte `Popover`
+- uses the resolved `versionLabel` for the active version when configured
 - displays each version option's `meta.label` when provided, otherwise the option name
 - navigates to the selected version's route root
 - scopes available versions to the current project
diff --git a/src/config/index.ts b/src/config/index.ts
index 48635f5..d2570ef 100644
--- a/src/config/index.ts
+++ b/src/config/index.ts
@@ -26,6 +26,7 @@ const SOLID_BASE_OVERRIDE_CONFIG_KEYS = [
 	"issueAutolink",
 	"lang",
 	"locales",
+	"versionLabel",
 	"themeConfig",
 	"editPath",
 	"lastUpdated",
@@ -46,6 +47,7 @@ export interface SolidBaseConfig<ThemeConfig> {
 	issueAutolink?: IssueAutoLinkConfig | false;
 	lang?: string;
 	locales?: Record<string, LocaleConfig<ThemeConfig>>;
+	versionLabel?: string;
 	routes?: SolidBaseRoutesConfig;
 	overrides?: Array<SolidBaseRouteOverride<ThemeConfig>>;
 	themeConfig?: ThemeConfig;
diff --git a/src/default-theme/components/VersionSelector.tsx b/src/default-theme/components/VersionSelector.tsx
index f4a70ff..80b677f 100644
--- a/src/default-theme/components/VersionSelector.tsx
+++ b/src/default-theme/components/VersionSelector.tsx
@@ -45,7 +45,9 @@ export default function VersionSelector() {
 						aria-label="Change version"
 						disabled={options().length <= 1}
 					>
-						<span class={styles.label}>{getOptionLabel(current())}</span>
+						<span class={styles.label}>
+							{config().versionLabel ?? getOptionLabel(current())}
+						</span>
 
 						<Show when={options().length > 1}>
 							<IconExpandUpDownLine class={styles.icon} aria-hidden />
diff --git a/tests/config/index.test.ts b/tests/config/index.test.ts
index b792d1a..e725cd3 100644
--- a/tests/config/index.test.ts
+++ b/tests/config/index.test.ts
@@ -141,7 +141,7 @@ describe("createSolidBase", () => {
 			solidBase.plugin({
 				routes: validRoutes,
 				overrides: [
-					{ version: "v1", title: "v1" },
+					{ version: "v1", versionLabel: "v1 (legacy)", title: "v1" },
 					{ locale: ["en", "fr"], themeConfig: { nav: [] } },
 				],
 			}),
diff --git a/tests/config/route-config.test.ts b/tests/config/route-config.test.ts
index 6467a0e..65699f0 100644
--- a/tests/config/route-config.test.ts
+++ b/tests/config/route-config.test.ts
@@ -227,6 +227,7 @@ describe("route config helpers", () => {
 						project: "solid",
 						version: "v1",
 						locale: "fr",
+						versionLabel: "v1 (legacy)",
 						title: "Solid v1 FR",
 					},
 				],
@@ -236,6 +237,7 @@ describe("route config helpers", () => {
 
 		expect(config).toMatchObject({
 			title: "Solid v1 FR",
+			versionLabel: "v1 (legacy)",
 			themeConfig: {
 				nav: ["solid"],
 				sidebar: { "/fr": [] },