docs(plugins): version breaking API guides (#4245)

Keep stable v0.7 guidance available while the client-entry layout is previewed for v0.8. Existing reference and migration URLs redirect to the release that owns their content.

packages/plugin/src/migration-doc.test.ts

@@ -9,7 +9,7 @@ describe("plugin runtime-entry migration guide", () => {
     if (!context) throw new Error("PluginClientContext was not found");
     const methods = [...context.matchAll(/^\s+(add[A-Z]\w*)\(/gm)].map((match) => match[1]);
     const migration = await readFile(
-      fileURLToPath(new URL("../../../public-docs/plugins/migration.md", import.meta.url)),
+      fileURLToPath(new URL("../../../public-docs/plugins/v0.8/migration.md", import.meta.url)),
       "utf8",
     );
     const table = migration.slice(

packages/server/src/server/plugins/runtime.posix.test.ts

@@ -507,7 +507,7 @@ export default function contribute(plugin: unknown) {
       "Plugin entry split is required",
     );
     await expect(runtime.startPlugin("legacy", directory)).rejects.toThrow(
-      "https://paseo.sh/docs/plugins/migration",
+      "https://paseo.sh/docs/plugins/v0.8/migration",
     );
   });
 

packages/server/src/server/plugins/runtime.ts

@@ -207,7 +207,7 @@ async function resolveEntryPaths(directory: string): Promise<{
   const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]);
   if (legacyEntry) {
     throw new Error(
-      "Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/migration",
+      "Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/v0.8/migration",
     );
   }
   throw new Error(

packages/website/src/docs.ts

@@ -157,6 +157,17 @@ export function getDoc(slug: string): Doc | undefined {
   return getDocs().find((d) => d.slug === slug);
 }
 
+const legacyPluginDocRedirects: Readonly<Record<string, string>> = {
+  "/docs/plugins/reference": "/docs/plugins/v0.7/reference",
+  "/docs/plugins/reference.md": "/docs/plugins/v0.7/reference.md",
+  "/docs/plugins/migration": "/docs/plugins/v0.8/migration",
+  "/docs/plugins/migration.md": "/docs/plugins/v0.8/migration.md",
+};
+
+export function getLegacyDocsRedirect(pathname: string): string | undefined {
+  return legacyPluginDocRedirects[pathname];
+}
+
 function formatLabel(segment: string): string {
   return segment.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }

packages/website/src/plugin-docs-navigation.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { buildDocsNavTree, getDocs, getLegacyDocsRedirect } from "./docs";
+
+describe("versioned plugin documentation", () => {
+  it("keeps current and preview releases together in the Plugins navigation", () => {
+    const plugins = buildDocsNavTree(getDocs()).find(
+      (node) => node.type === "category" && node.label === "Plugins",
+    );
+
+    expect(plugins).toMatchObject({
+      type: "category",
+      children: [
+        { type: "page", label: "Versions", href: "/docs/plugins" },
+        {
+          type: "group",
+          label: "Paseo v0.7 — Current",
+          href: "/docs/plugins/v0.7",
+          children: [{ type: "page", label: "Reference", href: "/docs/plugins/v0.7/reference" }],
+        },
+        {
+          type: "group",
+          label: "Paseo v0.8 — Preview",
+          href: "/docs/plugins/v0.8",
+          children: [
+            { type: "page", label: "Reference", href: "/docs/plugins/v0.8/reference" },
+            { type: "page", label: "Migration", href: "/docs/plugins/v0.8/migration" },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("keeps existing plugin documentation URLs working", () => {
+    expect(getLegacyDocsRedirect("/docs/plugins/reference")).toBe("/docs/plugins/v0.7/reference");
+    expect(getLegacyDocsRedirect("/docs/plugins/reference.md")).toBe(
+      "/docs/plugins/v0.7/reference.md",
+    );
+    expect(getLegacyDocsRedirect("/docs/plugins/migration")).toBe("/docs/plugins/v0.8/migration");
+    expect(getLegacyDocsRedirect("/docs/plugins/migration.md")).toBe(
+      "/docs/plugins/v0.8/migration.md",
+    );
+  });
+});

packages/website/src/server-entry.ts

@@ -1,7 +1,7 @@
 import startEntry from "@tanstack/react-start/server-entry";
 import { getAndroidVersionCode } from "~/android-version";
 import { getCanonicalRedirect } from "~/canonical-url";
-import { getDoc } from "~/docs";
+import { getDoc, getLegacyDocsRedirect } from "~/docs";
 import { getLatestAndroidVersion } from "~/latest-release";
 import { buildLlmsTxt } from "~/llms";
 
@@ -80,6 +80,12 @@ export default {
       return Response.redirect(url.toString(), 301);
     }
 
+    const legacyDocsRedirect = getLegacyDocsRedirect(url.pathname);
+    if (legacyDocsRedirect) {
+      url.pathname = legacyDocsRedirect;
+      return Response.redirect(url.toString(), 301);
+    }
+
     if (url.pathname === "/llms.txt") {
       return markdownResponse(buildLlmsTxt());
     }