ci: multiple ruby configuration fixes

.github/workflows/deploy-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Jekyll site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only one deployment at a time; don't cancel an in-progress run.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1.316.0
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true   # runs bundle install and caches gems automatically
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v6
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -5,3 +5,4 @@ deploy-preview/
 node_modules/
 scripts/
 package-lock.json
+.bundle/

.vscode/tasks.json

@@ -0,0 +1,43 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Jekyll: Serve (Docker)",
+      "type": "shell",
+      "command": "docker",
+      "args": [
+        "run", "--rm",
+        "--volume=${workspaceFolder}:/srv/jekyll:Z",
+        "-p", "4000:4000",
+        "-e", "BUNDLE_PATH=/srv/jekyll/.bundle",
+        "-w", "/srv/jekyll",
+        "jekyll/jekyll",
+        "sh", "-c",
+        "bundle install && bundle exec jekyll serve -H 0.0.0.0 --force_polling"
+      ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated",
+        "focus": true
+      },
+      "isBackground": true,
+      "problemMatcher": {
+        "pattern": {
+          "regexp": "^.*$",
+          "file": 1,
+          "line": 2,
+          "message": 3
+        },
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": "^.*bundle install.*$",
+          "endsPattern": "^.*Server running.*$"
+        }
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -10,17 +10,27 @@ a Ruby based static site generator, with [Just the Docs](https://github.com/just
 You can use the following Docker command to build and serve the site:
 
 ```shell
-cd spec.openapis.org
-rm Gemfile.lock # The docker image uses a different gem version which breaks with this one
 docker run --rm \
   --volume="$PWD:/srv/jekyll:Z" \
-  -p '4000:4000' \
+  -p 4000:4000 \
+  -e BUNDLE_PATH=/srv/jekyll/.bundle \
+  -w /srv/jekyll \
   jekyll/jekyll \
-  jekyll serve
+  sh -c "bundle install && bundle exec jekyll serve -H 0.0.0.0 --force_polling"
 ```
 
+On Windows (PowerShell), use `$PWD` as-is; the syntax is the same.
+
+The first run will download and install gems into `.bundle/` inside the
+repository. Subsequent runs reuse that cache and start much faster.
+
+If you are using VS Code, a pre-configured build task is included.
+Press `Ctrl+Shift+B` (or `Cmd+Shift+B` on macOS), or run
+**Tasks: Run Build Task** from the Command Palette, to start the
+container without having to type the command manually.
+
 (If `docker` is not running, check your Docker installation guide.
-On MacOS, for example, running the Docker IO will start the
+On macOS, for example, opening Docker Desktop will start the
 Docker daemon so the `docker` command will work.)
 
 ### Local Ruby dev

Gemfile

@@ -2,17 +2,19 @@
 
 source "https://rubygems.org"
 
-# gem "jekyll", "~> 4.4"
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
-gem "github-pages", "~> 232", group: :jekyll_plugins
-gem "webrick", "~> 1.9"
-gem "jekyll-remote-theme"
-gem "jekyll-include-cache", "~>0.2.1"
-gem "just-the-docs", "~> 0.12.0"
+gem "jekyll", "~> 4.4"
 
 group :jekyll_plugins do
-  gem "jekyll-sitemap", "~> 1.4"
+  gem "jekyll-remote-theme"
+  gem "jekyll-include-cache"
+  gem "jekyll-sitemap"
 end
 
+# Theme
+gem "just-the-docs", "~> 0.12.0"
+
+# Required for local development with Ruby 3.x
+gem "webrick", "~> 1.9"
+
+# Required for Ruby 3.4+ compatibility
 gem "bigdecimal", "~> 4.1"