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>
This commit is contained in:
polybjorn
2026-05-03 12:17:55 +00:00
committed by GitHub
parent c43930cfd1
commit 4b96b01460
5 changed files with 126 additions and 53 deletions

View File

@@ -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

View File

@@ -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'

View File

@@ -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

View File

@@ -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

View File

@@ -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>