chore(docs): upgrade Jekyll 3 to 4 and Ruby to 3.4.9 (#8772)

Jekyll 3 is unmaintained and its safe_yaml dependency breaks on
Ruby 3.4+ where base64 left the default stdlib. The docs workflow
already runs `bundle exec jekyll build` directly, so GitHub Pages'
Jekyll 3 lock does not apply here.

Changes:

* Pin `jekyll ~> 4.3`. Replace `jekyll-commonmark-ghpages` (pinned
  to Jekyll 3) with upstream `jekyll-commonmark`. Drop unused
  `jekyll-paginate`. Add `gem 'base64'` so the lockfile stays valid
  on Ruby 3.4+ where it became a bundled gem.
* Move CommonMark options into `_config.yml` to match what the
  `-ghpages` variant enabled by default: SMART, FOOTNOTES, UNSAFE
  (so inline HTML like `<br>` in tables still renders), plus the
  strikethrough, autolink, table, and tagfilter extensions. Set
  Rouge as the highlighter.
* Strip the leading slash from `defaults.scope.path` (`/en/*` to
  `en`). Jekyll 4 requires no leading slash, otherwise `page.lang`
  silently fails to propagate and `jekyll-i18n_tags` crashes the
  build.
* Pass `generateId=true` to the existing `anchor_headings.html`
  include so headings get slugified IDs. The `-ghpages` variant
  produced these by default.
* Bump CI Ruby to 3.4.9 and `cache-version` to invalidate the old
  Jekyll 3 gem cache on the first run.

Build is about 9x faster (1.0s vs 9.2s). Compared the rendered
output page by page against the Jekyll 3 baseline; remaining
differences are whitespace, footnote class names (no CSS depends
on either set), and one HTML entity (`&#8617;`) becoming the
literal `↩`. Visually and functionally the same.

Co-authored-by: Bjørn A. Andersen <polybjorn@users.noreply.github.com>

.github/workflows/jekyll-gh-pages.yml

@@ -33,9 +33,9 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f
         with:
-          ruby-version: '3.2.3' # Not needed with a .ruby-version file
+          ruby-version: '3.4.9'
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-          cache-version: 0 # Increment this number if you need to re-download cached gems
+          cache-version: 1 # Increment this number if you need to re-download cached gems
           working-directory: docs
       - name: Setup Pages
         uses: actions/configure-pages@v6

docs/Gemfile

@@ -1,13 +1,14 @@
 source "https://rubygems.org"
 
+gem "jekyll", "~> 4.3"
 gem "kramdown-parser-gfm"
+gem "base64" # Stdlib in Ruby <= 3.3, gem in 3.4+; pulled in by safe_yaml.
 
 group :jekyll_plugins do
   gem 'jekyll-coffeescript'
-  gem 'jekyll-commonmark-ghpages'
+  gem 'jekyll-commonmark'
   gem 'jekyll-gist'
   gem 'jekyll-github-metadata'
-  gem 'jekyll-paginate'
   gem 'jekyll-relative-links'
   gem 'jekyll-optional-front-matter'
   gem 'jekyll-readme-index'

docs/Gemfile.lock

@@ -3,65 +3,93 @@ GEM
   specs:
     addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
     coffee-script-source (1.12.2)
     colorator (1.1.0)
     commonmarker (0.23.12)
-    concurrent-ruby (1.3.5)
+    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)
-    execjs (2.10.0)
+    execjs (2.10.1)
     faraday (2.14.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
-    ffi (1.17.2)
-    ffi (1.17.2-aarch64-linux-gnu)
-    ffi (1.17.2-aarch64-linux-musl)
-    ffi (1.17.2-arm-linux-gnu)
-    ffi (1.17.2-arm-linux-musl)
-    ffi (1.17.2-arm64-darwin)
-    ffi (1.17.2-x86-linux-gnu)
-    ffi (1.17.2-x86-linux-musl)
-    ffi (1.17.2-x86_64-darwin)
-    ffi (1.17.2-x86_64-linux-gnu)
-    ffi (1.17.2-x86_64-linux-musl)
+    ffi (1.17.4)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86-linux-gnu)
+    ffi (1.17.4-x86-linux-musl)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
     forwardable-extended (2.6.0)
-    http_parser.rb (0.8.0)
-    i18n (1.14.7)
+    google-protobuf (4.34.1)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-aarch64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-aarch64-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    jekyll (3.10.0)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
       csv (~> 3.0)
       em-websocket (~> 0.5)
-      i18n (>= 0.7, < 2)
-      jekyll-sass-converter (~> 1.0)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
-      kramdown (>= 1.17, < 3)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (~> 0.3.3)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
-      rouge (>= 1.7, < 4)
+      rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
-      webrick (>= 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
     jekyll-coffeescript (2.0.0)
       coffee-script (~> 2.2)
       coffee-script-source (~> 1.12)
     jekyll-commonmark (1.4.0)
       commonmarker (~> 0.22)
-    jekyll-commonmark-ghpages (0.5.1)
-      commonmarker (>= 0.23.7, < 1.1.0)
-      jekyll (>= 3.9, < 4.0)
-      jekyll-commonmark (~> 1.4.0)
-      rouge (>= 2.0, < 5.0)
     jekyll-default-layout (0.1.5)
       jekyll (>= 3.0, < 5.0)
     jekyll-gist (1.5.0)
@@ -72,28 +100,28 @@ GEM
     jekyll-i18n_tags (1.0.0)
     jekyll-optional-front-matter (0.3.2)
       jekyll (>= 3.0, < 5.0)
-    jekyll-paginate (1.1.0)
     jekyll-readme-index (0.3.0)
       jekyll (>= 3.0, < 5.0)
     jekyll-relative-links (0.7.0)
       jekyll (>= 3.3, < 5.0)
-    jekyll-sass-converter (1.5.2)
-      sass (~> 3.4)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
     jekyll-titles-from-headings (0.5.3)
       jekyll (>= 3.3, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    json (2.19.2)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
+    json (2.19.4)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
-    listen (3.9.0)
+    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.3.6)
+    mercenary (0.4.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
     octokit (4.25.1)
@@ -102,49 +130,88 @@ GEM
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (7.0.5)
+    rake (13.4.2)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     rexml (3.4.4)
-    rouge (3.30.0)
+    rouge (4.7.0)
     safe_yaml (1.0.5)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
+    sass-embedded (1.99.0)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.99.0-aarch64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-aarch64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-aarch64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-androideabi)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-gnueabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-musleabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-musl)
+      google-protobuf (~> 4.31)
     sawyer (0.9.3)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
     uri (1.1.1)
     webrick (1.9.2)
 
 PLATFORMS
+  aarch64-linux-android
   aarch64-linux-gnu
   aarch64-linux-musl
+  arm-linux-androideabi
   arm-linux-gnu
+  arm-linux-gnueabihf
   arm-linux-musl
+  arm-linux-musleabihf
   arm64-darwin
+  riscv64-linux-android
+  riscv64-linux-gnu
+  riscv64-linux-musl
   ruby
   x86-linux-gnu
   x86-linux-musl
   x86_64-darwin
+  x86_64-linux-android
   x86_64-linux-gnu
   x86_64-linux-musl
 
 DEPENDENCIES
+  base64
+  jekyll (~> 4.3)
   jekyll-coffeescript
-  jekyll-commonmark-ghpages
+  jekyll-commonmark
   jekyll-default-layout
   jekyll-gist
   jekyll-github-metadata
   jekyll-i18n_tags
   jekyll-optional-front-matter
-  jekyll-paginate
   jekyll-readme-index
   jekyll-relative-links
   jekyll-titles-from-headings
   kramdown-parser-gfm
 
 BUNDLED WITH
-   2.7.2
+   2.6.9

docs/_config.yml

@@ -10,12 +10,12 @@ exclude: [CHANGELOG*.md, README.md, vendor]
 defaults:
   -
     scope:
-      path: "/en/*"
+      path: "en"
     values:
       lang: "en"
   -
     scope:
-      path: "/fr/*"
+      path: "fr"
     values:
       lang: "fr"
 
@@ -37,13 +37,18 @@ translations:
     choose_language: Choisir la langue
     copy_to_clipboard: Copier dans le presse-papiers
 
+markdown: CommonMark
+commonmark:
+  options: ["SMART", "FOOTNOTES", "UNSAFE"]
+  extensions: ["strikethrough", "autolink", "table", "tagfilter"]
+highlighter: rouge
+
 plugins:
   # gh
   - jekyll-coffeescript
-  - jekyll-commonmark-ghpages
+  - jekyll-commonmark
   - jekyll-gist
   - jekyll-github-metadata
-  - jekyll-paginate
   - jekyll-relative-links
   - jekyll-optional-front-matter
   - jekyll-readme-index

docs/_layouts/default.html

@@ -78,7 +78,7 @@
 		</aside>
 
     <main>
-			{% include anchor_headings.html html=content anchorBody="#" %}
+			{% include anchor_headings.html html=content anchorBody="#" generateId=true %}
     </main>
   </body>
 </html>