From f11e3855d98e2a7d8540aa000b42b0d78cd538c6 Mon Sep 17 00:00:00 2001
From: Hyan Mandian <5044101+hyanmandian@users.noreply.github.com>
Date: Tue, 13 Oct 2026 19:00:46 -0300
Subject: [PATCH 1/2] Old JavaScript docs links go to the utility they pointed
 at
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docsify site kept the section in the query string (/utilities?id=isvalidcpf,
/pt-br/utilities?id=cep-e-endereço). _redirects sends those to the JavaScript
library's page with the ?id= kept, and Google counted 137 of them as alternates of
that one page. The library's page now reads the id and replaces the location with
the utility's page (and the function's section), from /legacy-ids.json: the
JavaScript symbols from the last validator run, the utilities' titles and ids, and
the old page's other section headings. An unknown id stays on the library's page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RaUEDkvXY8rVWTJG2GKfhu
---
 site/src/app/legacy-ids.json/route.ts |  9 ++++
 site/src/components/pages/lib.tsx     |  8 ++++
 site/src/lib/legacy-ids.ts            | 64 +++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 site/src/app/legacy-ids.json/route.ts
 create mode 100644 site/src/lib/legacy-ids.ts

diff --git a/site/src/app/legacy-ids.json/route.ts b/site/src/app/legacy-ids.json/route.ts
new file mode 100644
index 0000000..91519cf
--- /dev/null
+++ b/site/src/app/legacy-ids.json/route.ts
@@ -0,0 +1,9 @@
+// /legacy-ids.json: where each anchor of the old JavaScript docs is now (see lib/legacy-ids.ts).
+// Only the JavaScript library's page reads it, and only when its URL has an ?id=.
+import { legacyIds } from '@/lib/legacy-ids';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return Response.json(legacyIds());
+}
diff --git a/site/src/components/pages/lib.tsx b/site/src/components/pages/lib.tsx
index b69eda8..a2dcad8 100644
--- a/site/src/components/pages/lib.tsx
+++ b/site/src/components/pages/lib.tsx
@@ -31,6 +31,13 @@ const show = (v: unknown) => (v === undefined || v === null ? 'null' : JSON.stri
 const LONG = 15;
 const GROUPS = ['failing', 'signature', 'missing'] as const;
 
+/**
+ * The old JavaScript docs' links (/utilities?id=isvalidcpf) arrive here through public/_redirects
+ * with their ?id= kept: this sends each to its utility's page. A redirect rule cannot read the query.
+ */
+const legacyRedirect = (locale: Locale) =>
+  `(function(){var id=new URLSearchParams(location.search).get('id');if(!id)return;fetch('${base}/legacy-ids.json').then(function(r){return r.json()}).then(function(m){var h=m[${JSON.stringify(locale)}][id.toLowerCase()];if(h)location.replace('${base}${prefixOf(locale)}'+h)}).catch(function(){})})()`;
+
 export async function LibPage({ locale, id }: { locale: Locale; id: string }) {
   const libs = loadLibs();
   const lib = libs.find((l: any) => l.id === id);
@@ -95,6 +102,7 @@ export async function LibPage({ locale, id }: { locale: Locale; id: string }) {
   return (
     <DocsPage slots={{ footer: DocsPager }} toc={toc} tableOfContent={{ style: 'clerk' }}>
       <PageJsonLd locale={locale} path={`/libs/${lib.id}/`} title={libTitle(locale, lib.label)} description={libDescription(locale, lib.label)} />
+      {lib.id === 'javascript' && <script dangerouslySetInnerHTML={{ __html: legacyRedirect(locale) }} />}
       <DocsTitle className="flex items-center gap-3">
         <LangIcon lib={lib.id} className="size-7" />
         {libTitle(locale, lib.label)}
diff --git a/site/src/lib/legacy-ids.ts b/site/src/lib/legacy-ids.ts
new file mode 100644
index 0000000..0d85435
--- /dev/null
+++ b/site/src/lib/legacy-ids.ts
@@ -0,0 +1,64 @@
+// Where the old JavaScript docs' anchors are now. That site (docsify) put a section in the query
+// string: /utilities?id=isvalidcpf for a function, /utilities?id=cep-e-endereço for a heading. Those
+// URLs land on the library's page (see public/_redirects), which sends each to its utility's page.
+import { loadSpecs, loadStatus } from './data';
+import { type Locale, pick } from './i18n';
+import { slug } from './prose';
+
+// The old page's section headings that are not a utility's title, in both languages.
+const SECTIONS: Record<string, string> = {
+  'cep-and-address': 'cep',
+  'cep-e-endereço': 'cep',
+  pix: 'pix-key',
+  'nf-e-key': 'nfe-key',
+  'chave-de-nf-e': 'nfe-key',
+  'nfs-e-key': 'nfse-key',
+  'chave-de-nfs-e': 'nfse-key',
+  pis: 'pis',
+  'processo-jurídico': 'legal-process',
+  'bank-accounts-and-banks': 'bank-account',
+  'contas-bancárias-e-bancos': 'bank-account',
+  'currency-numbers-and-dates-in-words': 'currency',
+  'moeda-números-e-datas-por-extenso': 'currency',
+  'states-and-municipalities': 'state',
+  'estados-e-municípios': 'state',
+  'holidays-and-business-days': 'date',
+  'feriados-e-dias-úteis': 'date',
+  'voter-id-título-de-eleitor': 'voter-id',
+  'título-de-eleitor': 'voter-id',
+  'certidão-civil-registry-certificate': 'certidao',
+  'cei-cno-and-caepf': 'cei',
+  'cei-cno-e-caepf': 'cei',
+  'gtin-product-barcode': 'gtin',
+  'gtin-código-de-barras-de-produto': 'gtin',
+  'inscrição-estadual-ie': 'ie',
+  'e-mail': 'email',
+  'credit-card': 'credit-card',
+  'cartão-de-crédito': 'credit-card',
+  'professional-registration': 'registro-profissional',
+  'registro-profissional': 'registro-profissional',
+  vin: 'vin',
+};
+
+/** Old anchor (lowercase) → the page, without the language prefix, in each language. */
+export function legacyIds() {
+  const status = loadStatus();
+  const js = status?.libs?.javascript?.functions ?? {};
+  const specs = loadSpecs() as any[];
+  const ids = new Set(specs.map((s) => s.id));
+  const out = {} as Record<Locale, Record<string, string>>;
+  for (const locale of ['en', 'pt-BR'] as Locale[]) {
+    const m: Record<string, string> = {};
+    for (const [key, id] of Object.entries(SECTIONS)) if (ids.has(id)) m[key] = `/utils/${id}/`;
+    for (const spec of specs) {
+      m[spec.id] ??= `/utils/${spec.id}/`;
+      for (const l of ['en', 'pt-BR'] as Locale[]) m[slug(pick(spec.title, l))] ??= `/utils/${spec.id}/`;
+      for (const op of spec.operations) {
+        const symbol = js[op.fnId]?.symbol;
+        if (symbol) m[symbol.toLowerCase()] = `/utils/${spec.id}/#${slug(pick(op.label, locale))}`;
+      }
+    }
+    out[locale] = m;
+  }
+  return out;
+}

From 236abbac9a4cf90664c7e1ce75c1c1c62d945360 Mon Sep 17 00:00:00 2001
From: Hyan Mandian <5044101+hyanmandian@users.noreply.github.com>
Date: Tue, 13 Oct 2026 19:14:29 -0300
Subject: [PATCH 2/2] A server-side 301 for the old links, instead of a script
 on the page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

public/_worker.js answers the old URLs with a 301 to the utility's page, from
/legacy-ids.json. _routes.json limits it to /utilities, /pt-br/utilities and the
JavaScript library's pages: every other request stays a static file. The
library's page no longer carries a script, and a crawler gets a real redirect
in one hop (/utilities?id=isvalidcpf → /utils/cpf/#validate) instead of two
plus a JavaScript one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RaUEDkvXY8rVWTJG2GKfhu
---
 site/public/_routes.json              |  5 +++++
 site/public/_worker.js                | 23 +++++++++++++++++++++++
 site/src/app/legacy-ids.json/route.ts |  2 +-
 site/src/components/pages/lib.tsx     |  8 --------
 site/src/lib/legacy-ids.ts            |  2 +-
 5 files changed, 30 insertions(+), 10 deletions(-)
 create mode 100644 site/public/_routes.json
 create mode 100644 site/public/_worker.js

diff --git a/site/public/_routes.json b/site/public/_routes.json
new file mode 100644
index 0000000..1575b1e
--- /dev/null
+++ b/site/public/_routes.json
@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "include": ["/utilities", "/utilities/", "/pt-br/utilities", "/pt-br/utilities/", "/libs/javascript/", "/pt-br/libs/javascript/"],
+  "exclude": []
+}
diff --git a/site/public/_worker.js b/site/public/_worker.js
new file mode 100644
index 0000000..90ca7e8
--- /dev/null
+++ b/site/public/_worker.js
@@ -0,0 +1,23 @@
+// Cloudflare Pages runs this only for the paths in _routes.json; every other request is a static
+// file. The old JavaScript docs (docsify) kept a section in the query string: /utilities?id=isvalidcpf
+// for a function, /pt-br/utilities?id=cep-e-endereço for a heading. A _redirects rule cannot read
+// a query string, so this sends each to its utility's page, from /legacy-ids.json (see
+// src/lib/legacy-ids.ts). Without a known id: /utilities goes to the library's page as before, and
+// the library's page is served as is.
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const pt = url.pathname.startsWith('/pt-br/');
+    const prefix = pt ? '/pt-br' : '';
+    const id = url.searchParams.get('id');
+    if (id) {
+      const res = await env.ASSETS.fetch(new URL('/legacy-ids.json', url));
+      if (res.ok) {
+        const to = (await res.json())[pt ? 'pt-BR' : 'en'][id.toLowerCase()];
+        if (to) return Response.redirect(new URL(prefix + to, url).toString(), 301);
+      }
+    }
+    if (/^(\/pt-br)?\/utilities\/?$/.test(url.pathname)) return Response.redirect(new URL(`${prefix}/libs/javascript/${url.search}`, url).toString(), 301);
+    return env.ASSETS.fetch(request);
+  },
+};
diff --git a/site/src/app/legacy-ids.json/route.ts b/site/src/app/legacy-ids.json/route.ts
index 91519cf..35e6990 100644
--- a/site/src/app/legacy-ids.json/route.ts
+++ b/site/src/app/legacy-ids.json/route.ts
@@ -1,5 +1,5 @@
 // /legacy-ids.json: where each anchor of the old JavaScript docs is now (see lib/legacy-ids.ts).
-// Only the JavaScript library's page reads it, and only when its URL has an ?id=.
+// public/_worker.js reads it for the old URLs that carry an ?id=.
 import { legacyIds } from '@/lib/legacy-ids';
 
 export const dynamic = 'force-static';
diff --git a/site/src/components/pages/lib.tsx b/site/src/components/pages/lib.tsx
index a2dcad8..b69eda8 100644
--- a/site/src/components/pages/lib.tsx
+++ b/site/src/components/pages/lib.tsx
@@ -31,13 +31,6 @@ const show = (v: unknown) => (v === undefined || v === null ? 'null' : JSON.stri
 const LONG = 15;
 const GROUPS = ['failing', 'signature', 'missing'] as const;
 
-/**
- * The old JavaScript docs' links (/utilities?id=isvalidcpf) arrive here through public/_redirects
- * with their ?id= kept: this sends each to its utility's page. A redirect rule cannot read the query.
- */
-const legacyRedirect = (locale: Locale) =>
-  `(function(){var id=new URLSearchParams(location.search).get('id');if(!id)return;fetch('${base}/legacy-ids.json').then(function(r){return r.json()}).then(function(m){var h=m[${JSON.stringify(locale)}][id.toLowerCase()];if(h)location.replace('${base}${prefixOf(locale)}'+h)}).catch(function(){})})()`;
-
 export async function LibPage({ locale, id }: { locale: Locale; id: string }) {
   const libs = loadLibs();
   const lib = libs.find((l: any) => l.id === id);
@@ -102,7 +95,6 @@ export async function LibPage({ locale, id }: { locale: Locale; id: string }) {
   return (
     <DocsPage slots={{ footer: DocsPager }} toc={toc} tableOfContent={{ style: 'clerk' }}>
       <PageJsonLd locale={locale} path={`/libs/${lib.id}/`} title={libTitle(locale, lib.label)} description={libDescription(locale, lib.label)} />
-      {lib.id === 'javascript' && <script dangerouslySetInnerHTML={{ __html: legacyRedirect(locale) }} />}
       <DocsTitle className="flex items-center gap-3">
         <LangIcon lib={lib.id} className="size-7" />
         {libTitle(locale, lib.label)}
diff --git a/site/src/lib/legacy-ids.ts b/site/src/lib/legacy-ids.ts
index 0d85435..35dbb81 100644
--- a/site/src/lib/legacy-ids.ts
+++ b/site/src/lib/legacy-ids.ts
@@ -1,6 +1,6 @@
 // Where the old JavaScript docs' anchors are now. That site (docsify) put a section in the query
 // string: /utilities?id=isvalidcpf for a function, /utilities?id=cep-e-endereço for a heading. Those
-// URLs land on the library's page (see public/_redirects), which sends each to its utility's page.
+// URLs reach public/_worker.js, which answers with a 301 to the utility's page from this map.
 import { loadSpecs, loadStatus } from './data';
 import { type Locale, pick } from './i18n';
 import { slug } from './prose';