Upgrade to Jekyll 4, drop github-pages gem (#81)#117
Merged
Conversation
The github-pages gem hard-pinned Jekyll 3.9 (plus old liquid/kramdown), which was the main cause of slow local builds (~30s). Since the site now publishes via a full `bundle exec jekyll build` in GitHub Actions (#98), the legacy GitHub Pages gem environment is no longer required. Replace it with the Jekyll 4 toolchain (resolves to 4.4.1). Measured cold build dropped from ~30s to ~17-20s locally. github-pages used to auto-enable several plugins implicitly; the ones this site relies on are now declared explicitly in the Gemfile's :jekyll_plugins group and in _config.yml `plugins:`: - jekyll-relative-links (rewrites internal .md links -> .html; ~20 pages depend on this) - jekyll-include-cache (just-the-docs uses {% include_cached %}) - jekyll-seo-tag (just-the-docs head dependency) - jekyll-sitemap (already declared) Other changes: - Switch remote_theme -> `theme: just-the-docs` (same 0.12.0 gem, no network/theme resolution at build time). - Add sass config: quiet_deps + sourcemap:never to reduce dart-sass deprecation noise from the theme's SCSS and stop emitting .css.map files. - Drop the no-op `cache: true` (not a real Jekyll config key). - Update the now-stale "still the github-pages gem" comment in jekyll.yml. Verified via isolated trial: _site output is byte-identical to the 3.x build except for benign deltas (seo-tag 2.8->2.9 meta formatting, generator string). Internal .md link resolution is unchanged. The only dropped page is /scripts/ (the dev-tools README, which has no front matter and nothing links to it). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #81.
Why
The
github-pagesgem hard-pinned Jekyll 3.9 (plus old liquid/kramdown), which was the main cause of slow local builds (~30s). Since the site now publishes via a fullbundle exec jekyll buildin GitHub Actions (#98), the legacy GitHub Pages gem environment is no longer required — so we're free to use Jekyll 4.What
github-pages, addgem "jekyll", "~> 4.3"(resolves to 4.4.1).github-pagesused to auto-enable several plugins implicitly. The ones this site relies on are now declared explicitly in the Gemfile:jekyll_pluginsgroup and in_config.ymlplugins::jekyll-relative-links— rewrites internal.mdlinks →.html; ~20 content pages depend on this (without it, every internal link 404s).jekyll-include-cache— just-the-docs uses{% include_cached %}.jekyll-seo-tag— just-the-docs head dependency.jekyll-sitemap— already declared.remote_theme→theme: just-the-docs(same 0.12.0 gem, no network/theme resolution at build time).sass: { quiet_deps: true, sourcemap: never }to reduce dart-sass deprecation noise from the theme's SCSS and stop emitting.css.mapfiles.cache: true(not a real Jekyll config key).jekyll.yml. No workflow logic change — it already runsbundle exec jekyll build, so it picks up Jekyll 4 automatically.Verification
Ran an isolated trial (baseline build → migrate → rebuild → diff
_site/):jekyll-seo-tag2.8→2.9 meta formatting and theJekyllgenerator string. No content/structural changes..mdlink resolution is unchanged — raw.mdhrefs are byte-identical to the 3.x build (the few that remain are pre-existing broken links in source content, unrelated to this change)./scripts/(the dev-tools README, which has no front matter and is described as "not part of the build"); nothing links to it (0 inbound links).Notes / things to confirm in CI
html-proofercouldn't run in my local Windows env (nolibcurl); the link gate runs on the Linux CI runner. Output parity + no new broken links means it should pass exactly as on baseline.Gemfile.lockis gitignored, so CI resolves from theGemfilefresh (unchanged behavior).@importdeprecation warnings from the theme's own SCSS remain (non-failing); fully silenceable later.🤖 Generated with Claude Code