Skip to main content
undefined
undefined

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

undefined

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Upgrading a Jekyll site to Ruby 3.1

May 24, 2023

Ruby 2.7 has reached “end of life” so we’re providing instructions on how to upgrade your Jekyll site to use Ruby 3.1. Cloud.gov Pages will continue supporting Ruby 2.7 builds for six months, but then only Ruby 3 versions will be supported.

The main difficulty with upgrading a site to use a newer version of Ruby is that one or more of your required Gems could break when changing Ruby versions. This is notably the case for jekyll-assets . If you don’t have that dependency, this could be a relatively straightforward upgrade. We recently upgraded our own Jekyll template repo which you can check out for reference.

Instructions for sites without jekyll-assets

If you don’t see jekyll-assets  in your Gemfile  or Gemfile.lock , you don’t have a dependency on jekyll-assets  and you might be able to upgrade to Ruby 3.1 with just a few steps:

  • Create a file called .ruby-version  in your site folder which contains the string 3.1 . If you already have this file, you can replace the previous version with 3.1 
  • If you have any other site-specific scripts which specify the ruby version, update these as well.
  • Add or change your specified Ruby version (e.g. ruby '~> 3.1' ).Delete your previous Gemfile.lock  and regenerate by running bundle install 
    • If this command adds a new PLATFORM  to your Gemfile.lock , and it’s anything other than ruby , remove it with the following command:
      • bundle lock --remove-platform example_platform_name . For example bundle lock --remove-platform arm64-darwin-21 
  • Commit and push all these changes to see if the cloud.gov Pages build succeeds!

Instructions for sites with jekyll-assets

Jekyll Assets is a helpful gem for compiling SASS, JS, and image files into your final jekyll build. Unfortunately it is unmaintained and hasn’t been updated in three years. It also doesn’t support Ruby 3. So if you remove it, you’ll need alternative ways to make sure your SASS, JS, and image files are included in your site build correctly.
We’ve documented the migration process in a PR to our deprecated jekyll template and included the main steps below. Your site may have specific customizations which make some of these steps not applicable.

  • Create a file called .ruby-version  in your site folder which contains the string 3.1 . If you already have this file, you can replace the previous version with 3.1 .

  • If you have any other site-specific scripts which specify the ruby version, update these as well.

  • Remove jekyll-assets  from your Gemfile . Add or change your specified Ruby version (e.g. ruby '~> 3.1' ). Delete your previous Gemfile.lock  and regenerate by running bundle install 

    • If this command adds a new PLATFORM  to your Gemfile.lock , and it’s anything other than ruby , remove it with the following command:
      • bundle lock --remove-platform example_platform_name . For example bundle lock --remove-platform arm64-darwin-21 
    • You may need to add ruby  as a platform, as bundle  now requires at least one platform, using bundle lock --add-platform ruby 

  • [The hard step] Replace the primary functionality of jekyll-assets:

    • First move everything from the _assets  folder to the assets  folder
    • Remove any uses of the {% asset %}  liquid tag or asset_url  function in your content. This tag and function provided a way to find a given asset in any of multiple specified site folders. You’ll likely want to replace this with /img/example.png  or {{ /assets/example.png | relative_url }}  where example.png  is the name of the example file.
    • Move all SASS partials to a new folder called _sass . You can leave the entrypoint SASS file (styles.scss) in assets/css  but you’ll need to add two sets of triple dashes to the start of the file.
    • Add our two helper jekyll plugins to the _plugins  folder:
      • asset-helper.rb  copies USWDS assets from the node_modules  folder into your assets  folder
      • autoprefixer.rb  roughly recreates the functionality of jekyll-autoprefixer  and adds vendor prefixes to CSS rules
    • You’ll need to update _config.yml  to reflect passing configuration options to our new plugins instead of jekyll-assets . You can see an example configuration change in our template PR.
    • Add a new empty file called .gitkeep  in assets/uswds  and then add these three lines to .gitignore  to ignore temporary USWDS assets during the build:
    assets/uswds/*
!assets/uswds/.gitkeep
assets/js/uswds*

    Note that these upgrades will temporarily make your site builds slower (but more secure!). We’re working on an alternative build container which uses Ruby 3.1 as its default. Please reach out to us at pages-support@cloud.gov with any questions about this process.