From 2b734f28b5e6ff2fd543053a48c2054c1d88e59d Mon Sep 17 00:00:00 2001
From: Marie Chatfield <marie.chatfield@gusto.com>
Date: Fri, 25 Sep 2026 13:29:09 -0700
Subject: [PATCH] fix: cap live docs site to 5 most recent SDK minors
 (SDK-1344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is the actual source of truth for docs-site config — it's synced
into Gusto/embedded-sdk-docs on release and clobbers any local fix
there. The equivalent change landed in embedded-sdk-docs#28 but got
overwritten by the next sync (SDK 0.56.2), reintroducing the OOM.

Building every minor's full doc set on every release OOMs the
Buildkite build once enough snapshots accumulate. Restrict
onlyIncludeVersions to the latest 5; older minors' markdown stays in
git history and is now linked from the 404 page to the matching
v<X.Y>.0 tag.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs-site/docusaurus.config.ts                | 15 ++++++++++----
 .../src/theme/NotFound/Content/index.tsx      | 20 +++++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs-site/docusaurus.config.ts b/docs-site/docusaurus.config.ts
index 125c73e45f..91f8b32c06 100644
--- a/docs-site/docusaurus.config.ts
+++ b/docs-site/docusaurus.config.ts
@@ -31,6 +31,12 @@ const versions: string[] = rawVersions
 const lastVersion = versions[0]
 const hasVersions = lastVersion !== undefined
 
+// Building every minor's full doc set on every release OOMs — cap the live site
+// to the most recent minors. Older minors' markdown still lives in the GitHub repo and
+// is served, unversioned, from the corresponding tag.
+const MAX_BUILT_VERSIONS = 5
+const builtVersions = versions.slice(0, MAX_BUILT_VERSIONS)
+
 const config: Config = {
   title: 'Gusto Embedded',
   tagline: 'Embedded Payroll React SDK Documentation',
@@ -206,8 +212,9 @@ const config: Config = {
           ...(hasVersions && {
             lastVersion,
             includeCurrentVersion: false,
+            onlyIncludeVersions: builtVersions,
             versions: Object.fromEntries(
-              versions.map(version => [version, { banner: 'none' as const, badge: false }]),
+              builtVersions.map(version => [version, { banner: 'none' as const, badge: false }]),
             ),
           }),
         },
@@ -216,9 +223,9 @@ const config: Config = {
           // robots.txt blocks crawlers from fetching older-minor snapshots; keep
           // them out of the sitemap too, so it advertises only the canonical,
           // unprefixed /docs/<page> (the latest minor, driven by lastVersion).
-          // versions[0] is that latest minor served unprefixed, so slice(1) drops
-          // just the /docs/<X.Y>/ snapshots — no maintenance as new minors land.
-          ignorePatterns: hasVersions ? versions.slice(1).map(v => `/docs/${v}/**`) : [],
+          // builtVersions[0] is that latest minor served unprefixed, so slice(1)
+          // drops just the /docs/<X.Y>/ snapshots — no maintenance as new minors land.
+          ignorePatterns: hasVersions ? builtVersions.slice(1).map(v => `/docs/${v}/**`) : [],
           changefreq: 'weekly',
           priority: 0.5,
         },
diff --git a/docs-site/src/theme/NotFound/Content/index.tsx b/docs-site/src/theme/NotFound/Content/index.tsx
index 2ba3141aa8..34b4ae8d8f 100644
--- a/docs-site/src/theme/NotFound/Content/index.tsx
+++ b/docs-site/src/theme/NotFound/Content/index.tsx
@@ -1,11 +1,19 @@
 import Link from '@docusaurus/Link'
+import { useLocation } from '@docusaurus/router'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 import Heading from '@theme/Heading'
 import type { ReactNode } from 'react'
 import styles from './styles.module.css'
 
+// Only the most recent minors are built into the live site (SDK-1344); older
+// /docs/<X.Y>/ paths 404 here. Point readers at the git tag with the same
+// content instead of leaving them stranded.
+const OLD_VERSION_PATH = /^\/docs\/(\d+\.\d+)\//
+
 export default function NotFoundContent(): ReactNode {
   const homeUrl = useBaseUrl('/')
+  const { pathname } = useLocation()
+  const oldVersionMatch = OLD_VERSION_PATH.exec(pathname)
 
   return (
     <div className={styles.root}>
@@ -16,6 +24,18 @@ export default function NotFoundContent(): ReactNode {
         <p className={styles.subtitle}>
           The page you&apos;re looking for doesn&apos;t exist or has been moved.
         </p>
+        {oldVersionMatch && (
+          <p className={styles.subtitle}>
+            Looking for SDK {oldVersionMatch[1]} docs? Older versions aren&apos;t published on this
+            site, but the source is preserved at{' '}
+            <a
+              href={`https://github.com/Gusto/embedded-react-sdk/tree/v${oldVersionMatch[1]}.0/docs`}
+            >
+              v{oldVersionMatch[1]}.0/docs
+            </a>{' '}
+            in Gusto/embedded-react-sdk.
+          </p>
+        )}
         <div className={styles.links}>
           <Link to={homeUrl} className={styles.homeLink}>
             Go to Home