diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index b389d6d..e9088e2 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -1,19 +1,20 @@
 name: documentation
 
+# Validates that the docs site still builds. Deployment lives in
+# main-docs.yml, which publishes to gh-pages using the automatic
+# GITHUB_TOKEN and needs no configured secret.
 on:
   pull_request:
     branches: [main]
-  push:
-    branches: [main]
 
 jobs:
   checks:
-    if: github.event_name != 'push'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
+          # Docusaurus 3 requires Node >= 20
           node-version: '20.x'
       - name: Test Build
         run: |
@@ -26,30 +27,3 @@ jobs:
             npm i
           fi
           npm run build
-  gh-release:
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v1
-      - uses: actions/setup-node@v1
-        with:
-          node-version: '20.x'
-      - uses: webfactory/ssh-agent@v0.5.0
-        with:
-          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
-      - name: Release to GitHub Pages
-        env:
-          USE_SSH: true
-          GIT_USER: git
-        run: |
-          cd docs
-          git config --global user.email "saifulislam84210@gmail.com"
-          git config --global user.name "Saif Ul Islam"
-          if [ -e yarn.lock ]; then
-            yarn install --frozen-lockfile
-          elif [ -e package-lock.json ]; then
-            npm ci
-          else
-            npm i
-          fi
-          npm run deploy
diff --git a/.github/workflows/main-docs.yml b/.github/workflows/main-docs.yml
index ab6b464..0e5c28a 100644
--- a/.github/workflows/main-docs.yml
+++ b/.github/workflows/main-docs.yml
@@ -1,23 +1,29 @@
-on: [push]
+name: deploy documentation
+
+# Builds the docs site and publishes it to the gh-pages branch, which is what
+# GitHub Pages serves. Authenticates with the automatic GITHUB_TOKEN, so there
+# is no deploy key or secret to maintain.
+on:
+  push:
+    branches: [main]
 
 jobs:
   build_docs_job:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: [3.6]
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
-    - name: Dependencies
-      run: |
-        sudo apt-get install -y yarn
-      id: build
+      uses: actions/checkout@v4
+    - name: Set up Node
+      uses: actions/setup-node@v4
+      with:
+        # Docusaurus 3 requires Node >= 20. This was previously left to the
+        # runner default, which happened to be new enough but was not pinned.
+        node-version: '20.x'
     - name: Build the Website
       run: |
         cd docs
-        yarn
-        npm run build  
+        yarn install --frozen-lockfile
+        npm run build
     - name: Deploy
       uses: JamesIves/github-pages-deploy-action@releases/v3
       with: