fix(docs): enforce Node.js >=20 and upgrade Docusaurus to 3.9.2 (#437)

* fix(docs): enforce Node.js >=20 and upgrade Docusaurus to 3.9.2

* build(ci): enable docs workflow on PRs and use Node 20

* build(ci): add PR preview workflow

* fix(ci): correct pull_request trigger type to synchronize

* fix(ci): use pull_request_target for preview deployment permissions

Author: vibhatha

.github/workflows/deploy-docs.yml

@@ -6,6 +6,9 @@ on:
       - main
     paths:
       - 'docs/**'
+  pull_request:
+    paths:
+      - 'docs/**'
   workflow_dispatch:
 
 permissions:
@@ -22,7 +25,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: npm
           cache-dependency-path: docs/package-lock.json
 
@@ -33,6 +36,7 @@ jobs:
         run: npm run build
 
       - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/preview-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy PR Preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source_dir: docs/build
+          preview_branch: gh-pages
+          umbrella_dir: pr-preview
+          action: auto
+          # We need to build the site within the action context or before
+          # rossjrw action can run a build command, but it's often easier to run the build ourselves
+          # provided we can set the env var. 
+          # Actually, the action supports a 'build_script' input.
+          build_script: npm run build
+          # We need to pass the BASE_URL env var to the build script.
+          # The action doesn't natively expose a way to inject env vars into the build_script 
+          # easily unless we wrap it or use the 'env' map at the step level.
+        env:
+          # The action calculates the preview URL. We need to construct the matching Base URL.
+          # Default format is: /<umbrella_dir>/<pr_number>/
+          # But we are deployed at /OpenGIN/. So it will be /OpenGIN/pr-preview/<pr_number>/
+          BASE_URL: /OpenGIN/pr-preview/${{ github.event.number }}/

docs/.nvmrc

@@ -0,0 +1 @@
+20

docs/docusaurus.config.js

@@ -14,13 +14,17 @@ const config = {
   tagline: 'Open General Information Network',
   favicon: 'img/opengin_blue.png',
 
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
 
 
   // Set the production url of your site here
   url: 'https://LDFLK.github.io',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
-  baseUrl: '/OpenGIN/',
+  baseUrl: process.env.BASE_URL || '/OpenGIN/',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.