[JAMES-4175] upgrade jekyll version

Updates build documentation
Creates dedicated nix devshell for jekyll in the homepage directory

Author: jeantil

docs/modules/community/pages/contributing.adoc

@@ -194,7 +194,9 @@ patch is more likely to be committed quickly.
 
 There is work in progress to support a more reproductible dev environment so you don't have to figure out what to install or how.
 
-If you already have the nix package manager installed you should be able to use the following command to enter the predefined build env :
+This work is based on nix flakes if you are not familiar with nix or flakes you can find more information in the https://nix.dev/manual/nix/2.28/command-ref/new-cli/nix3-flake.html[official documentation], https://wiki.nixos.org/wiki/Flakes[official wiki] or in https://zero-to-nix.com/concepts/flakes/[dedicated] community https://nix.dev/concepts/flakes[resources].
+
+If you already have the nix package manager installed you should be able to use the following command to enter the predefined build env (experimental nix flag `flakes` is required, `nix-command` is recommended as it is used in many examples) with  :
 
 ```
 nix develop --no-update-lock-file

docs/modules/community/pages/website.adoc

@@ -22,49 +22,92 @@ https://james.staged.apache.org[staging version] of the website.
 ====
 
 == Building the homepage
+
 You can use jekyll to build the website. Go into `{path}` and run the following command
 
-[,shell]
+=== Docker
+
+[WARNING]
+====
+The official docker image `jekyll/jekyll` is unmaintained and is not compatible with jekyll version beyond 4.2.2.
+In this documentation we suggest a replacement `jvconseil/jekyll-docker` but note that this is not an official image.
+Use at your own risks.
+====
+
+[source,shell]
 ----
-$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jekyll/jekyll:$JEKYLL_VERSION  jekyll build
+$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build
 ----
 
 The resulting deployable content will be available in the `{path}/_site/`
 directory.
 
 In order to test the homepage, you can use this command:
-[,shell]
+[source,shell]
 ----
-$ docker run --rm -v $PWD/site:/srv/jekyll  -p 4000:4000 -it jekyll/jekyll jekyll serve
+$ docker run --rm -v $PWD/site:/srv/jekyll -p 4000:4000 -it jvconseil/jekyll-docker:4 jekyll serve
 ----
 The site will be available at http://localhost:4000/
 
 
 If you need to update the current site, checkout the branch asf-site from
 Apache git:
-[,shell]
+[source,shell]
 ----
 $ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
 $ cd james-site
 $ git checkout origin/asf-site -b asf-site
 ----
 
-And replace in the previous commands `$PWD/site` by
-`<james-site-clone-directory>/content`, for example:
+make sure to build the site then copy the output to
 
-[,shell]
+[source,shell]
 ----
-$ docker run -v $PWD:/origin -v $PWD/../james-site/content:/destination james/homepage master
-$ docker run -v $PWD/.m2:/root/.m2 -v $PWD/../james-site/content:/origin -v $PWD/site:/destination james/site master
+$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build
+$ cp  ../james-site/content
 ----
 
 Then just push the new site:
-[,shell]
+[source,shell]
 ----
 $ cd ../james-site
 $ git push origin asf-site
 ----
 
+=== Experimental nix environment
+
+From the root of the repository checkout, you can use the flake's devshell
+
+[source,shell]
+----
+$ cd src/homepage
+$ nix develop
+----
+
+Then use jekyll directly
+
+[source,shell]
+----
+$ jekyll serve
+# or
+$ jekyll build
+----
+
+==== Gemset update for nix
+
+Updating the gemset to track the gemfile updates is a bit involved :
+
+. ensure you are out of all nix devshell (check using `echo $SHLVL` it should be 1)
+. create a temporary shell for gem manipulation `nix-shell -p ruby -p bundix`
+. update the gemfile then run
++
+[,shell]
+----
+BUNDLE_FORCE_RUBY_PLATFORM="true" bundle lock --update
+bundix -l
+----
+. exit the temporary shell and enter the devShell again `nix develop`
+
 == Maven site
 
 The maven site deploy phase uses and requires locally configuring credentials to
@@ -100,7 +143,7 @@ The docker file in `src/site-docker` is currently broken:
 prepare for some tinkering before building using this method.
 ====
 
-[,shell]
+[source,shell]
 ----
 $ docker build -t james/site src/site-docker
 $ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master
@@ -109,7 +152,7 @@ $ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination jam
 === Nix development shell
 
 Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
-development shell]
+development shell] with `nix develop`.
 
 1. run `mvn clean package site -Djib.skip`
 2. Test the built site in your browser from the `{path}/target/site` folder

docs/modules/community/partials/antora.adoc

@@ -48,7 +48,7 @@ Go to `http://localhost` in your browser.
 === Build with the nix enviroment
 
 Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
-development shell]
+development shell] with `nix develop`
 
 . Build the Antora content locally
 +

flake.nix

@@ -29,11 +29,11 @@
           packages = with pkgs; [
             antora  # build documentation
             bundler # homepage and blog
+            bundix
             cacert  # ssl certificate management
             dive    # explore generated docker images
             git     # version control
             jdk     # build and run james
-            jekyll  # homepage and blog
             maven   # build james
           ];
           MAVEN_OPTS = "-Djna.library.path="  + pkgs.lib.makeLibraryPath [pkgs.udev];

src/homepage/Gemfile.lock

@@ -1,72 +1,94 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     colorator (1.1.0)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.15.5)
+    ffi (1.17.3)
+    ffi (1.17.3-x86_64-linux-musl)
     forwardable-extended (2.6.0)
-    http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    google-protobuf (4.34.0)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.0-x86_64-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    jekyll (4.2.2)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
+      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
-      jekyll-sass-converter (~> 2.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
-      kramdown (~> 2.3)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (~> 0.4.0)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
-      rouge (~> 3.0)
+      rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
-      terminal-table (~> 2.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
     jekyll-feed (0.17.0)
       jekyll (>= 3.7, < 5.0)
-    jekyll-sass-converter (2.2.0)
-      sassc (> 2.0.1, < 3.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.4.0)
-      rexml
+    json (2.18.1)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    liquid (4.0.3)
-    listen (3.7.1)
+    liquid (4.0.4)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     mercenary (0.4.0)
-    minima (2.5.1)
+    minima (2.5.2)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.0)
+    public_suffix (7.0.2)
+    rake (13.3.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
-    rouge (3.30.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
     safe_yaml (1.0.5)
-    sassc (2.4.0)
-      ffi (~> 1.9)
-    terminal-table (2.0.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    unicode-display_width (1.8.0)
+    sass-embedded (1.97.3)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.97.3-x86_64-linux-musl)
+      google-protobuf (~> 4.31)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
     webrick (1.9.2)
 
 PLATFORMS
+  ruby
   x86_64-linux-musl
 
 DEPENDENCIES
@@ -75,7 +97,7 @@ DEPENDENCIES
   webrick
 
 RUBY VERSION
-   ruby 3.1.1p18
+   ruby 3.3.10p183
 
 BUNDLED WITH
    2.3.25

src/homepage/flake.nix

@@ -0,0 +1,42 @@
+{
+  description = "james homepage build env";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+  };
+
+  outputs =
+    { self, nixpkgs }@inputs:
+    let
+      forAllSystems = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all;
+    in
+    {
+      devShell = forAllSystems (
+        system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          env = pkgs.bundlerEnv {
+            name = "james homepagebuild env";
+            gemdir = ./.;
+            groups = [
+              "default"
+              "development"
+              "test"
+            ];
+
+            meta = with pkgs.lib; {
+              description = "james homepagebuild env";
+              platforms = platforms.unix;
+            };
+          };
+        in
+        pkgs.mkShell {
+          buildInputs = [
+            env
+            env.wrappedRuby
+            pkgs.bundix
+          ];
+        }
+      );
+    };
+}