feat(docs-archive): add 1.5.0 and switch to prebuilt Vercel deploy

docs-archive/.gitignore

@@ -4,6 +4,9 @@
 # Production
 /build
 
+# Vercel prebuilt output (generated by scripts/deploy/package-prebuilt.sh)
+/.vercel
+
 # Generated files
 .docusaurus
 .cache-loader

docs-archive/docusaurus.config.js

@@ -31,9 +31,10 @@ const config = {
           routeBasePath: '/docs',
           includeCurrentVersion: false,
           sidebarPath: require.resolve('./sidebars.js'),
-          // 1.3.0 is "latest" in this archive — served without version prefix
-          lastVersion: '1.3.0',
+          // 1.5.0 is the newest version in this archive
+          lastVersion: '1.5.0',
           versions: {
+            '1.5.0': { label: '1.5.0', banner: 'none', path: '1.5.0' },
             '1.3.0': { label: '1.3.0', banner: 'none', path: '1.3.0' },
             '1.1.0': { label: '1.1.0', banner: 'none', path: '1.1.0' },
             '1.0.0': { label: '1.0.0', banner: 'none', path: '1.0.0' },
@@ -79,7 +80,7 @@ const config = {
           dropdownItemsBefore: [
             {
               href: 'https://docs.datahub.com',
-              label: '1.4.0 (Latest) ↗',
+              label: 'Latest ↗',
             },
             {
               type: 'html',
@@ -125,8 +126,8 @@ const config = {
         {
           title: 'Docs',
           items: [
-            { label: 'Introduction', to: 'docs/1.3.0/features' },
-            { label: 'Quickstart', to: 'docs/1.3.0/quickstart' },
+            { label: 'Introduction', to: 'docs/1.5.0/features' },
+            { label: 'Quickstart', to: 'docs/1.5.0/quickstart' },
           ],
         },
         {
@@ -141,7 +142,7 @@ const config = {
         {
           title: 'More',
           items: [
-            { label: 'Latest Docs (1.4.0)', href: 'https://docs.datahub.com' },
+            { label: 'Latest Docs ↗', href: 'https://docs.datahub.com' },
             { label: 'Roadmap', href: 'https://feature-requests.datahubproject.io/roadmap' },
             { label: 'GitHub', href: 'https://github.com/datahub-project/datahub' },
           ],

docs-archive/scripts/deploy/README.md

@@ -0,0 +1,43 @@
+# Docs archive — deploy scripts
+
+This archive builds many documentation versions with Docusaurus in a single
+site. That build is memory-intensive and can exceed the memory available on
+hosted build environments. To avoid that, we build the static site in an
+environment we control and then upload the finished output to Vercel, so Vercel
+serves it without rebuilding.
+
+## Flow
+
+```bash
+# 1. Build the static site -> build/
+./scripts/deploy/build-archive.sh
+
+# 2. Wrap build/ into Vercel's Build Output API layout -> .vercel/output/
+./scripts/deploy/package-prebuilt.sh
+
+# 3. Upload the prebuilt output (Vercel serves it as-is, no rebuild).
+export VERCEL_TOKEN=...            # provide via a secret; never commit it
+export VERCEL_ORG_ID=...
+export VERCEL_PROJECT_ID=...
+npx vercel deploy --prebuilt --prod --yes --token="$VERCEL_TOKEN"
+```
+
+## Why `--prebuilt`
+
+`--prebuilt` tells Vercel to upload the contents of `.vercel/output/` directly
+instead of building from source. This keeps the build in an environment with
+enough memory and avoids rebuilding on deploy.
+
+## Vercel project settings
+
+- The archive is its own Vercel project, served at `archive.docs.datahub.com`.
+- Git-triggered deploys should be disabled for that project so a push does not
+  start a build from source. Deploys are expected to run via the CLI with
+  `--prebuilt`.
+
+## Committed vs generated
+
+- **Committed:** documentation source (`versioned_docs/`, configs) and these
+  scripts.
+- **Generated (git-ignored):** `build/`, `.docusaurus/`, `node_modules/`,
+  `.vercel/`.

docs-archive/scripts/deploy/build-archive.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# Build the docs archive with the memory settings needed for the full
+# multi-version Docusaurus build.
+#
+# Output lands in docs-archive/build/ (Docusaurus static output).
+# Run scripts/deploy/package-prebuilt.sh next to wrap it for Vercel.
+#
+set -euo pipefail
+
+ARCHIVE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ARCHIVE_DIR"
+
+# Raise the V8 heap limit and serialize SSR to keep peak memory manageable.
+# The server compile needs well above the default heap; run this on a machine
+# (or runner) with enough RAM to back the limit below, or provide swap.
+export NODE_OPTIONS="--max-old-space-size=20480"
+export DOCUSAURUS_SSR_CONCURRENCY=1
+
+echo ">> Building docs archive in $ARCHIVE_DIR"
+rm -rf build .docusaurus
+npm run build
+echo ">> Build complete -> $ARCHIVE_DIR/build"

docs-archive/scripts/deploy/package-prebuilt.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+#
+# Wrap the finished Docusaurus build/ into Vercel's Build Output API (v3)
+# layout at docs-archive/.vercel/output/, so that:
+#
+#     npx vercel deploy --prebuilt --prod
+#
+# uploads the already-built site without Vercel rebuilding it from source.
+#
+# Run build-archive.sh first to produce build/.
+#
+set -euo pipefail
+
+ARCHIVE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BUILD_DIR="$ARCHIVE_DIR/build"
+OUTPUT_DIR="$ARCHIVE_DIR/.vercel/output"
+
+if [ ! -d "$BUILD_DIR" ] || [ ! -f "$BUILD_DIR/index.html" ]; then
+  echo "ERROR: no build found at $BUILD_DIR — run scripts/deploy/build-archive.sh first." >&2
+  exit 1
+fi
+
+echo ">> Packaging $BUILD_DIR -> $OUTPUT_DIR"
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR/static"
+
+# Copy the entire static site into the Build Output API's static/ folder.
+cp -R "$BUILD_DIR"/. "$OUTPUT_DIR/static/"
+
+# Minimal valid config for a purely static site. Vercel serves static/ as-is
+# and uses the generated 404.html for not-found routes automatically.
+cat > "$OUTPUT_DIR/config.json" <<'JSON'
+{
+  "version": 3
+}
+JSON
+
+echo ">> Prebuilt output ready at $OUTPUT_DIR"
+echo ">> Deploy with: (cd $ARCHIVE_DIR && npx vercel deploy --prebuilt --prod --yes --token=\$VERCEL_TOKEN)"