ci(docs): Optimise build performance with caching and conditional Node.js

Skip installing Node.js entirely if v20+ is already available, otherwise
install v22. Add npm dependency caching with OS-specific cache keys using
the custom detect-runner-os action for proper cache isolation between
runners. Dependencies normally take just under 10s, so this should more
than halve the doc build time to free up runner slots.

.forgejo/actions/detect-runner-os/action.yml

@@ -13,6 +13,12 @@ outputs:
   slug:
     description: 'Combined OS slug (e.g. Ubuntu-22.04)'
     value: ${{ steps.detect.outputs.slug }}
+  node_major:
+    description: 'Major version of Node.js if available (e.g. 22)'
+    value: ${{ steps.detect.outputs.node_major }}
+  node_version:
+    description: 'Full Node.js version if available (e.g. 22.19.0)'
+    value: ${{ steps.detect.outputs.node_version }}
 
 runs:
   using: composite
@@ -30,7 +36,20 @@ runs:
         # Create combined slug
         OS_SLUG="${OS_NAME}-${OS_VERSION}"
 
-        # Set outputs
+        # Detect Node.js version if available
+        if command -v node >/dev/null 2>&1; then
+          NODE_VERSION=$(node --version | sed 's/v//')
+          NODE_MAJOR=$(echo $NODE_VERSION | cut -d. -f1)
+          echo "node_version=${NODE_VERSION}" >> $GITHUB_OUTPUT
+          echo "node_major=${NODE_MAJOR}" >> $GITHUB_OUTPUT
+          echo "🔍 Detected Node.js: v${NODE_VERSION}"
+        else
+          echo "node_version=" >> $GITHUB_OUTPUT
+          echo "node_major=" >> $GITHUB_OUTPUT
+          echo "🔍 Node.js not found"
+        fi
+
+        # Set OS outputs
         echo "name=${OS_NAME}" >> $GITHUB_OUTPUT
         echo "version=${OS_VERSION}" >> $GITHUB_OUTPUT
         echo "slug=${OS_SLUG}" >> $GITHUB_OUTPUT

.forgejo/workflows/documentation.yml

@@ -49,10 +49,23 @@ jobs:
           cp ./docs/static/_headers ./public/_headers
           echo "Copied .well-known files and _headers to ./public"
 
+      - name: Detect runner environment
+        id: runner-env
+        uses: ./.forgejo/actions/detect-runner-os
+
       - name: Setup Node.js
+        if: steps.runner-env.outputs.node_major == '' || steps.runner-env.outputs.node_major < '20'
         uses: https://github.com/actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
+
+      - name: Cache npm dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ steps.runner-env.outputs.slug }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ steps.runner-env.outputs.slug }}-node-
 
       - name: Install dependencies
         run: npm install --save-dev wrangler@latest