feat: Upgrade from Jekyll 3.x to 4.x

[smockle]

Rationale

Jekyll 4.x allows Catalyst to use Kramdown 2.3.0, as suggested by CVE 2020-14001.

Jekyll 3.x to 4.x Upgrade Guide

The upgrade guide notes several changes:

• Ruby ≥2.5.0 required — Catalyst could add a .ruby-version file to make this requirement explicit, though since Ruby 2.5.0 was released in 2017, I imagine many folks already have a newer version installed—anecdotally, I did.

• post_url now prepends site.baseurl — git grep post_url did not show any matches, so this change does not (directly) affect Catalyst.

• Templates are now parsed once, then cached and rendered multiple times — I don’t know how to asses the impact of this. The description for this change mentions some plugins may behavior differently as a result. docs/_config.yml lists one plugin, jekyll-github-metadata.

• Collections (other than posts) not configured with output: true aren’t outputted — Catalyst’s guide collection is configured with output: true, so this change does not affect Catalyst.

• site.liquid_renderer.file(path).parse(content) is now idempotent (for path) — git grep liquid_renderer did not show any matches, so this change does not (directly) affect Catalyst. Additionally, the description for this change mentions it is relevant to plugin authors, but this is a Jekyll site, not a plugin.

• exclude in _config.yml is now additive, and the default exclude list has expanded — docs/_config.yml’s exclude configuration is now redundant and can be removed, though I haven’t to keep this changeset small and testable/reviewable.

• Jekyll dropped support for Kramdown 1.x — This was the precipitating reason for this PR, as described above. It’s worth noting that Kramdown 2.0.0 introduced its own set of breaking changes.

• Deprecated configuration options have been removed — docs/_config.yml does not include any deprecated configuration options, so this change does not affect Catalyst.

🚨 Before Merging 🚨

While testing this branch locally, I’ve noticed the following unexpected behavior, which we should investigate further before merging:

1. The warning GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data. is logged when running bundle exec jekyll build or bundle exec jekyll serve in the docs directory. (Update: Ignoring, as advised)

2. Instead of navigating, clicking the “Reference” button on http://127.0.0.1:4000 duplicates the heading (GIF below). No errors appear in Terminal or the Safari Developer Tools Console. (Update: Fixed in b7fc3d4)

[koddsson]

This seems good to me 👍🏻

1. The warning GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data. is logged when running bundle exec jekyll build or bundle exec jekyll serve in the docs directory.

I think this is fine if the page is otherwise working.

2. Instead of navigating, clicking the “Reference” button on http://127.0.0.1:4000 duplicates the heading (GIF below). No errors appear in Terminal or the Safari Developer Tools Console.

I can't reproduce locally 🤷🏻

[keithamus]

👍

[smockle]

2. Instead of navigating, clicking the “Reference” button on http://127.0.0.1:4000 duplicates the heading (GIF below). No errors appear in Terminal or the Safari Developer Tools Console.

I can't reproduce locally 🤷🏻

I can consistently repro it in Safari when the viewport is wider than 1280px. It seems to be related to the <br class="hide-sm"> in index.html—when I remove that break, things work as expected. Still debugging to figure out what’s going on, but I don’t think it’s related/caused by this PR’s update to Jekyll 4.x.

I suspect it’s something like Flexbug #11:

Safari uses min/max width/height declarations for actually rendering the size of flex items, but it ignores those values when calculating how many items should be on a single line of a multi-line flex container. Instead, it simply uses the item's flex-basis value, or its width if the flex basis is set to auto.

[smockle]

1. Instead of navigating, clicking the “Reference” button on http://127.0.0.1:4000 duplicates the heading (GIF below). No errors appear in Terminal or the Safari Developer Tools Console.

I can't reproduce locally 🤷🏻

I can consistently repro it in Safari when the viewport is wider than 1280px. It seems to be related to the <br class="hide-sm"> in index.html—when I remove that break, things work as expected. Still debugging to figure out what’s going on, but I don’t think it’s related/caused by this PR’s update to Jekyll 4.x.

I suspect it’s something like Flexbug #11:

Safari uses min/max width/height declarations for actually rendering the size of flex items, but it ignores those values when calculating how many items should be on a single line of a multi-line flex container. Instead, it simply uses the item's flex-basis value, or its width if the flex basis is set to auto.

Update: Fixed in b7fc3d4