From 4b96b0146006fe002e85292109b0d5594adbe97b Mon Sep 17 00:00:00 2001 From: polybjorn Date: Sun, 3 May 2026 12:17:55 +0000 Subject: [PATCH] chore(docs): upgrade Jekyll 3 to 4 and Ruby to 3.4.9 (#8772) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 `
` 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 (`↩`) becoming the literal `↩`. Visually and functionally the same. Co-authored-by: Bjørn A. Andersen --- .github/workflows/jekyll-gh-pages.yml | 4 +- docs/Gemfile | 5 +- docs/Gemfile.lock | 155 ++++++++++++++++++-------- docs/_config.yml | 13 ++- docs/_layouts/default.html | 2 +- 5 files changed, 126 insertions(+), 53 deletions(-) diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index f06992aa1..48a186afc 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.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 diff --git a/docs/Gemfile b/docs/Gemfile index 76d06a741..fa497d637 100644 --- a/docs/Gemfile +++ b/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' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 130f1007c..78bc9d6ea 100644 --- a/docs/Gemfile.lock +++ b/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 diff --git a/docs/_config.yml b/docs/_config.yml index e90f6bd2d..4dd69eb94 100644 --- a/docs/_config.yml +++ b/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 diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 252e1024d..e34fbfc0c 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -78,7 +78,7 @@
- {% include anchor_headings.html html=content anchorBody="#" %} + {% include anchor_headings.html html=content anchorBody="#" generateId=true %}