Proposal: deploy via a committed GitHub Actions workflow and drop the `github-pages` gem

Disclaimer: the following are the findings when I tried to debug #2991 . The contents are drafted via Claude Fable 5.1. I believe these changes are sensible and are entitled for the v1.0 release with breaking changes.

* * *

## Summary

The template currently relies on GitHub's built-in Pages builder (`pages-build-deployment`) and mirrors it locally through the `github-pages` gem. That gem pins the whole toolchain to versions GitHub chose in August 2024, and GitHub has shown no intention of moving them. I propose that the template ship a `jekyll.yml` deploy workflow, make "Source: GitHub Actions" the documented setup path, and replace `gem 'github-pages'` with explicit dependencies. This is what unblocks #2991 and removes a recurring class of breakage.

## What the `github-pages` gem pins today

`github-pages` 232 (released 2024-08-06, still the latest) hard-pins, among others:

| gem | pinned |
|---|---|
| jekyll | = 3.10.0 |
| kramdown | = 2.4.0 |
| kramdown-parser-gfm | = 1.1.0 |
| jekyll-feed / -sitemap / -redirect-from / -gist / -paginate / jemoji | fixed old versions |

Because the built-in builder (`actions/jekyll-build-pages@v1`) ignores the repository's `Gemfile` entirely, users cannot override any of this today. The gem's only job is to keep local builds identical to that environment.

## Why this hurts the template

1. **#2991 is unfixable under the current setup.** `header_links` was added in kramdown 2.5.0 (2024-11-18) and does not exist in 2.4.0, so the option is silently ignored. The GFM parser is not the limitation; the pinned version is.
2. **GitHub will not lift the pins.** github/pages-gem#651 "Support for Jekyll 4.0" has been open since 2019 with 80+ comments. Jekyll 4 was released in 2019. Waiting is not a strategy.
3. **Surprise breakage on GitHub's schedule, not ours.** When GitHub bumped the gem in February 2024, sites across the template broke at once (#1900, #1902). A committed workflow with a committed `Gemfile.lock` makes builds reproducible and lets maintainers choose when to upgrade.
4. **Local setup keeps breaking.** #2061, #3150, #3321 and the README's own advice ("if you get errors, delete Gemfile.lock and try again") are largely a consequence of pinning 2022-era gems against current Rubies (Ruby 3.4 removing default gems such as `csv`, `base64`, etc.).
5. **Plugin ceiling.** The built-in builder runs with `--safe` and a fixed whitelist, which is why requests such as jekyll-scholar (#684) can only be answered with "not possible". Under Actions, any gem in the `Gemfile` works.

## Proposal

### 1. Add `.github/workflows/jekyll.yml`

Essentially GitHub's own starter workflow: `actions/checkout`, `ruby/setup-ruby` with `bundler-cache: true`, `actions/configure-pages`, `bundle exec jekyll build`, `actions/upload-pages-artifact`, `actions/deploy-pages`. `actions/configure-pages` supports `enablement: true`, which turns on Pages with the Actions source automatically, so new users may not even need to visit Settings.

### 2. Replace `gem 'github-pages'` in `Gemfile` with explicit pins

Stage A (zero rendering change, same versions as today, just spelled out):

```ruby
group :jekyll_plugins do
gem 'jekyll', '~> 3.10'
gem 'jekyll-feed'
gem 'jekyll-sitemap'
gem 'jekyll-redirect-from'
gem 'jekyll-gist'
gem 'jekyll-paginate'
gem 'jemoji'
gem 'webrick', '~> 1.8'
end
gem 'kramdown', '~> 2.4'
gem 'kramdown-parser-gfm'
```

Stage B: bump `kramdown` to `~> 2.5` (jekyll 3.10 allows `>= 1.17, < 3`) and set `header_links: true` plus a small SCSS rule for the anchor. This closes #2991.

Stage C (separate discussion, later): evaluate Jekyll 4.x.

### 3. Commit `Gemfile.lock`

It is currently in `.gitignore`. Committing it is what makes CI and local builds identical, which is the property the `github-pages` gem was trying to provide. `bundler-cache: true` also keys its cache on the lockfile.

### 4. Update README / docs

Replace step 6 ("Check status ... in the GitHub pages section") with: Settings → Pages → Source → "GitHub Actions". Update the `pages-build-deployment` badge to the new workflow. Update `Dockerfile` (it already copies only the `Gemfile`, so it needs no structural change).

## Impact on existing users

* Existing forks are unaffected until they pull the change; the built-in builder keeps working for them.
* Users who pull the change and do not switch the Pages source will keep being built by the built-in builder, which still works (it ignores `Gemfile`). They just do not get the new features. No one is broken by default.
* Actions minutes are free for public repositories, which is the template's documented use case (`username.github.io`).

## Prior art

* GitHub's own recommendation for Jekyll sites needing newer versions or plugins is the Actions workflow: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
* Minimal Mistakes (the theme this template descends from) documents the same path.

Related: #2991, #1900, #1902, #2061, #3150, #3321, #684, github/pages-gem#651.