From 4deaf37fdc62d3f39235f83459b0db9e81b7e2a4 Mon Sep 17 00:00:00 2001
From: Greg Annandale <greg@raspberrypi.org>
Date: Wed, 20 May 2026 10:41:06 +0100
Subject: [PATCH] chore(docs): remove unneeded client redirects, add
 server-side redirects

---
 package-lock.json                  | 25 -------------------------
 packages/docs/docusaurus.config.js | 15 ---------------
 packages/docs/package.json         |  1 -
 packages/docs/static/_redirects    | 10 ++++++++++
 4 files changed, 10 insertions(+), 41 deletions(-)
 create mode 100644 packages/docs/static/_redirects

diff --git a/package-lock.json b/package-lock.json
index c066b4a92..f177b9cfb 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4108,30 +4108,6 @@
         "react-dom": "*"
       }
     },
-    "node_modules/@docusaurus/plugin-client-redirects": {
-      "version": "3.9.2",
-      "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.9.2.tgz",
-      "integrity": "sha512-lUgMArI9vyOYMzLRBUILcg9vcPTCyyI2aiuXq/4npcMVqOr6GfmwtmBYWSbNMlIUM0147smm4WhpXD0KFboffw==",
-      "license": "MIT",
-      "dependencies": {
-        "@docusaurus/core": "3.9.2",
-        "@docusaurus/logger": "3.9.2",
-        "@docusaurus/utils": "3.9.2",
-        "@docusaurus/utils-common": "3.9.2",
-        "@docusaurus/utils-validation": "3.9.2",
-        "eta": "^2.2.0",
-        "fs-extra": "^11.1.1",
-        "lodash": "^4.17.21",
-        "tslib": "^2.6.0"
-      },
-      "engines": {
-        "node": ">=20.0"
-      },
-      "peerDependencies": {
-        "react": "^18.0.0 || ^19.0.0",
-        "react-dom": "^18.0.0 || ^19.0.0"
-      }
-    },
     "node_modules/@docusaurus/plugin-content-blog": {
       "version": "3.9.2",
       "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-3.9.2.tgz",
@@ -29299,7 +29275,6 @@
       "license": "Apache-2.0",
       "dependencies": {
         "@docusaurus/core": "3.9.2",
-        "@docusaurus/plugin-client-redirects": "^3.9.2",
         "@docusaurus/preset-classic": "3.9.2",
         "@mdx-js/react": "^3.0.1",
         "clsx": "^2.1.1",
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
index 7cce90805..abe15e604 100644
--- a/packages/docs/docusaurus.config.js
+++ b/packages/docs/docusaurus.config.js
@@ -35,21 +35,6 @@ const config = {
     locales: ['en'],
   },
 
-  plugins: [
-    [
-      '@docusaurus/plugin-client-redirects',
-      {
-        fromExtensions: ['md', 'mdx'],
-        createRedirects(existingPath) {
-          if (existingPath.startsWith('/reference/')) {
-            return [existingPath.replace('/reference/', '/reference/js/')];
-          }
-          return undefined;
-        },
-      },
-    ],
-  ],
-
   presets: [
     [
       'classic',
diff --git a/packages/docs/package.json b/packages/docs/package.json
index e62af97d0..8aa08f691 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -20,7 +20,6 @@
   },
   "dependencies": {
     "@docusaurus/core": "3.9.2",
-    "@docusaurus/plugin-client-redirects": "^3.9.2",
     "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.1",
     "clsx": "^2.1.1",
diff --git a/packages/docs/static/_redirects b/packages/docs/static/_redirects
new file mode 100644
index 000000000..63a16db93
--- /dev/null
+++ b/packages/docs/static/_redirects
@@ -0,0 +1,10 @@
+# Cloudflare Pages Redirects
+# Syntax: source destination [status_code]
+# https://developers.cloudflare.com/pages/configuration/redirects/
+
+# Legacy /reference/js/* paths redirect to canonical /reference/* URLs
+/reference/js/*   /reference/:splat   302
+
+# Strip .md/.mdx extensions if someone lands on the raw filename
+/reference/*.md   /reference/:splat   302
+/reference/*.mdx  /reference/:splat   302