Skip to content

Upgrade to Jekyll 4, drop github-pages gem (#81)#117

Merged
jonfroehlich merged 3 commits into
mainfrom
feat/jekyll4-build-speedup
Jun 23, 2026
Merged

Upgrade to Jekyll 4, drop github-pages gem (#81)#117
jonfroehlich merged 3 commits into
mainfrom
feat/jekyll4-build-speedup

Conversation

@jonfroehlich

Copy link
Copy Markdown
Member

Closes #81.

Why

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 — so we're free to use Jekyll 4.

What

  • Drop github-pages, add gem "jekyll", "~> 4.3" (resolves to 4.4.1).
  • github-pages used to auto-enable several plugins implicitly. The ones this site relies on are now declared explicitly in the Gemfile :jekyll_plugins group and in _config.yml plugins::
    • jekyll-relative-links — rewrites internal .md links → .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.
  • Switch remote_themetheme: just-the-docs (same 0.12.0 gem, no network/theme resolution at build time).
  • Add sass: { quiet_deps: true, sourcemap: never } to reduce dart-sass deprecation noise from the theme's SCSS and stop emitting .css.map files.
  • Remove the no-op cache: true (not a real Jekyll config key).
  • Update the now-stale "still the github-pages gem" comment in jekyll.yml. No workflow logic change — it already runs bundle exec jekyll build, so it picks up Jekyll 4 automatically.

Verification

Ran an isolated trial (baseline build → migrate → rebuild → diff _site/):

  • Build time: ~30s → ~17–20s locally (cold build).
  • Output parity: every page differs only for benign global reasons — jekyll-seo-tag 2.8→2.9 meta formatting and the Jekyll generator string. No content/structural changes.
  • Internal .md link resolution is unchanged — raw .md hrefs are byte-identical to the 3.x build (the few that remain are pre-existing broken links in source content, unrelated to this change).
  • Only dropped page is /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-proofer couldn't run in my local Windows env (no libcurl); the link gate runs on the Linux CI runner. Output parity + no new broken links means it should pass exactly as on baseline.
  • Gemfile.lock is gitignored, so CI resolves from the Gemfile fresh (unchanged behavior).
  • A handful (~21) of cosmetic dart-sass @import deprecation warnings from the theme's own SCSS remain (non-failing); fully silenceable later.

🤖 Generated with Claude Code

jonfroehlich and others added 2 commits June 23, 2026 12:02
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>
@jonfroehlich jonfroehlich merged commit b03209f into main Jun 23, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Build times super slow

1 participant