From 931c96f7d79bb7838903c99a18299c13ce050db9 Mon Sep 17 00:00:00 2001
From: bomanaps <mercy.boma35@yahoo.com>
Date: Sun, 5 Apr 2026 16:19:34 +0100
Subject: [PATCH 1/4] docs: add site versioning support

---
 api_versions.json    | 1 +
 docusaurus.config.ts | 8 ++++++++
 package.json         | 3 ++-
 3 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 api_versions.json

diff --git a/api_versions.json b/api_versions.json
new file mode 100644
index 000000000..fe51488c7
--- /dev/null
+++ b/api_versions.json
@@ -0,0 +1 @@
+[]
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 42a08798a..dcda76f34 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -38,6 +38,13 @@ const config: Config = {
       path: 'docs-api',
       routeBasePath: '/',
       sidebarPath: './docs-api/sidebars.ts',
+      lastVersion: 'current',
+      versions: {
+        current: {
+          label: 'Next',
+          badge: false,
+        },
+      },
     }],
     ['@docusaurus/plugin-client-redirects', {
       redirects: [{ from: '/api', to: '/' }],
@@ -74,6 +81,7 @@ const config: Config = {
       title: 'Execution APIs',
       items: [
         { type: 'docSidebar', sidebarId: 'docsSidebar', docsPluginId: 'api', label: 'Docs', position: 'left' },
+        { type: 'docsVersionDropdown', docsPluginId: 'api', position: 'right' },
         { href: 'https://github.com/ethereum/execution-apis', label: 'GitHub', position: 'right' },
       ],
     },
diff --git a/package.json b/package.json
index ca7128cbe..81603dc0c 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,8 @@
     "serve": "docusaurus serve",
     "clear": "docusaurus clear",
     "watch": "nodemon --watch src --watch docs-api/docs --watch README.md --ignore docs-api/docs/quickstart.md --ext yaml,md,json --exec \"npm run build:spec && npm run docs:copy\"",
-    "docs:copy": "cp README.md ./docs-api/docs/quickstart.md"
+    "docs:copy": "cp README.md ./docs-api/docs/quickstart.md",
+    "docs:version": "docusaurus docs:version:api"
   },
   "repository": {
     "type": "git",

From 60026326363d6c4991a9bfea31dcfdc89a14059c Mon Sep 17 00:00:00 2001
From: bomanaps <mercy.boma35@yahoo.com>
Date: Wed, 8 Apr 2026 14:47:02 +0100
Subject: [PATCH 2/4] add release workflow to attach openrpc

---
 .github/workflows/release.yaml | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 .github/workflows/release.yaml

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
new file mode 100644
index 000000000..1cf233b85
--- /dev/null
+++ b/.github/workflows/release.yaml
@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  attach-openrpc-spec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: ^1.26
+        id: go
+
+      - name: Build the spec
+        run: make build
+
+      - name: Upload OpenRPC spec to release
+        run: |
+          gh release upload ${{ github.event.release.tag_name }} openrpc.json refs-openrpc.json
+        env:
+          GH_TOKEN: ${{ github.token }}

From c0d9c8bbc2c7cb0ad8f5a932e04ec63763e19662 Mon Sep 17 00:00:00 2001
From: bomanaps <mercy.boma35@yahoo.com>
Date: Thu, 9 Apr 2026 18:14:11 +0100
Subject: [PATCH 3/4] add versioned docs pipeline to deploy workflow

---
 .github/workflows/deploy.yaml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index 5be77d449..8a7281b46 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -20,6 +20,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-go@v6
         with:
@@ -38,6 +40,17 @@ jobs:
       - name: Install JS dependencies
         run: npm ci
 
+      - name: Create versioned doc snapshots
+        run: |
+          VERSIONS=$(python3 -c "import json; vs=json.load(open('api_versions.json')); print('\n'.join(vs))")
+          if [ -n "$VERSIONS" ]; then
+            for VERSION in $VERSIONS; do
+              git checkout "refs/tags/$VERSION" -- docs-api/
+              npm run docs:version -- "$VERSION"
+            done
+            git checkout HEAD -- docs-api/
+          fi
+
       - name: Build docs
         run: npm run build:docs
 

From 16e17740f175db8364ad662d81f4bd39c0b6e6e9 Mon Sep 17 00:00:00 2001
From: bomanaps <mercy.boma35@yahoo.com>
Date: Mon, 27 Apr 2026 00:11:24 +0100
Subject: [PATCH 4/4] switched to Node for consistency

---
 .github/workflows/deploy.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index 8a7281b46..a0dcf4f98 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -42,7 +42,7 @@ jobs:
 
       - name: Create versioned doc snapshots
         run: |
-          VERSIONS=$(python3 -c "import json; vs=json.load(open('api_versions.json')); print('\n'.join(vs))")
+          VERSIONS=$(node -e "console.log(require('./api_versions.json').join('\n'))")
           if [ -n "$VERSIONS" ]; then
             for VERSION in $VERSIONS; do
               git checkout "refs/tags/$VERSION" -- docs-api/