Remove references to long outdated and unmaintained `github-pages` gem from the docs

[0xdevalias]

Code of Conduct

• [x] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

As per this comment by @TWiStErRob, there are still references to the legacy github-pages gem in the docs:

• https://github.com/github/pages-gem/issues/890#issuecomment-1913562792

Such as:

• https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site
  • https://github.com/github/docs/blob/main/content/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll.md

Yet as best as I have been able to tell, this gem has been unmaintained and considered legacy since GitHub pages switched to GitHub actions in 2022, if not earlier:

• https://github.com/github/pages-gem/issues/651#issuecomment-2712968982

It would be good if the docs could be updated appropriately, and ideally if an appropriate team could officially mark the github-pages gem deprecated/legacy so that people stop asking.

What part(s) of the article would you like to see updated?

Everything to do with the legacy github-pages gem.

Additional information

See above.

[subatoi]

Many thanks for reporting that @0xdevalias — we'll investigate this internally.

Unfortunately as we're not GitHub Support, I can't guarantee a timeframe for the response, but I'll leave this issue open until we can say something definitive.

Thanks for your interest in the GitHub docs!

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[0xdevalias]

Unfortunately as we're not GitHub Support, I can't guarantee a timeframe for the response, but I'll leave this issue open until we can say something definitive.

@subatoi No worries, I appreciate it :)

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[Sharra-writes]

Hi, @0xdevalias 👋 After conferring with our SMEs, they tell us that GitHub.com and especially GHES are both still relying on this gem, making deprecation impractical at the moment. While that is eventually a goal, right now there are still too many legacy users to pursue it. Sorry we can't do it right now, but thank you for bringing it up so we could look into its feasibility. Please feel free to bring up any other topics that you would like to see discussed and hopefully pursued. We always appreciate your desire to improve the docs. 💛

[TWiStErRob]

Isn't it technically deprecated already as there's no maintenance going on (last commit: 6 months, last release: 10 months, open PRs: from 2022), we only asking for documentation update to reflect the reality:

• so new users are less confused on what to invest time on
• existing users have guidance on best practices (even if it means migration to experimental, but stable features)

The fact that GitHub internally uses it, doesn't mean the public should be too? Also the reason there are many legacy users is because it is the recommended way at the moment?

[0xdevalias]

Hi @Sharra-writes 👋 — thank you (and the rest of the internal team) for taking the time to investigate and respond.

I wanted to clarify that while I did use the word deprecated in my original message — which I understand may not align with GitHub’s internal usage policies or current support realities — my intent (as @TWiStErRob helpfully echoed) was not necessarily to request formal deprecation, but rather to help clarify for end users what the currently recommended and actively maintained approach is.

Right now, the documentation still prominently refers to the legacy github-pages gem as if it's the default or preferred method, despite it seeing minimal updates and trailing behind modern best practices. This can be especially confusing for new users who are trying to figure out the “right” path forward, only to find themselves investing time into tooling that is not seeing meaningful maintenance.

Even a small note or callout in the relevant docs — indicating that while the gem is still in use internally (and in GHES), GitHub Actions-based workflows are now the more flexible and modern option for most use cases — would go a long way toward guiding users to better-supported setups and helping reduce legacy lock-in over time.

Appreciate your openness and all the work you and the team do to maintain the docs 💛

[philoserf]

If the team needs to better understand the old ecosystem, @benbalter is still at GitHub.

[Sharra-writes]

@0xdevalias That is definitely a more limited scope. Let me check into it and see what the rest of the team thinks. I'll reopen this so I can track it more easily.

[Sharra-writes]

@0xdevalias I finally got the go-ahead from both the docs and pages teams, so we can discuss the kind of note you think would work best. My instinct is a call-out at the beginning of the article you've mentioned here along the lines of "Jekyll is no longer being updated, and Actions is better for most use-cases," with a link to whatever "about Actions" or quickstart article we have. But that's just initial thoughts, I'm definitely open to other options. Are there any other articles you know of that would benefit from the same treatment?

[0xdevalias]

I finally got the go-ahead from both the docs and pages teams

@Sharra-writes Awesome!

My instinct is a call-out at the beginning of the article you've mentioned here along the lines of "Jekyll is no longer being updated, and Actions is better for most use-cases,"

@Sharra-writes I haven't gone back to review the docs pages/thought this through deeply; but something like that definitely seems like the right sort of approach, and to align with patterns I've seen on other GitHub docs with 'callouts'.

Are there any other articles you know of that would benefit from the same treatment?

@Sharra-writes I haven't had time to go looking specifically just now, but as a default I guess as an end-user, I would sort of want it that any docs page I ended up on that was recommending using the gem would either a) be updated to suggest the actions based workflow instead, or b) call out that the gem is not the recommended choice anymore (except in whatever caveat cases there may be), etc.

As a starting point for finding docs pages that could benefit from this, I would look at those mentioned earlier in this issue, as well as skimming through the following 2 issues (off the top of my head) to see if they've discussed any others:

• https://github.com/github/pages-gem/issues/651
• https://github.com/github/pages-gem/issues/890

Also probably just doing a general search through the docs for github pages and the gem and clicking through related links/pages to see what comes up.

I'm not sure when I will have capacity, but if I can, I will try and do what I suggested above and give some more specifics; unless someone else manages to before I get to it.

[Sharra-writes]

@0xdevalias I'll see if I can get some time to help with the search, but my first priority will be putting together a reusable to simplify the updates.

[Sharra-writes]

@0xdevalias So in the course of making my reusable, I realized that this information is actually very poorly presented in the "who can use this feature" box at the top of each page. That's a really weird place to put it, not the least because it has nothing to do with who can use the feature, which probably contributes to the fact that no one appears to read it. But it does include some details for implementing Jekyll with Actions that I'm not seeing elsewhere in the documentation:

When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly.

Do you have thoughts on how essential this information is to have documented? I mean, right now it's not even searchable since it's not showing up in my search results, and it's in a section with a label that has nothing to do with the topic. So...I'm not sure anything will be missed if I cut it without inserting it elsewhere?

[0xdevalias]

Do you have thoughts on how essential this information is to have documented?

@Sharra-writes If the .nojekyll part isn't documented elsewhere, and it is still valid, then I think that is essential to keep somewhere.

And if the GitHub actions part is a requirement for publishing from a branch these days, then I think it should definitely be documented. This was linked through from the settings page, and would seem a useful spot where it doesn't already seem to be said:

• https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch

This might also be a good place to include, or perhaps link to, a page with more details about how the github-pages gem is used (if it is) for that 'publish from a branch' 'classic pages experience'. Or at least somewhere in the docs I think it would be useful to know exactly which products it is still used with; and where it isn't relevant (eg. because jekyll is just used directly/similar).

---

Looking at the pages settings on my blog repo (which I haven't updated in a long time):

• https://github.com/0xdevalias/devalias.net/settings/pages

It seems to be configured to use 'deploy from a branch' which appears to use the 'classic pages experience':

The 'Learn more about configuring the publishing source for your site' text links through to:

• https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

While I'm not sure this is the best sole place for this information to exist, under 'Troubleshooting publishing from a branch' (which doesn't even seem to show up in the right hand 'In this article' menu.. which feels wrong), the .nojekyll part seems to be mentioned:

Your GitHub Pages site will always be deployed with a GitHub Actions workflow run, even if you've configured your GitHub Pages site to be built using a different CI tool. Most external CI workflows "deploy" to GitHub Pages by committing the build output to the gh-pages branch of the repository, and typically include a .nojekyll file. When this happens, the GitHub Actions workflow will detect the state that the branch does not need a build step, and will execute only the steps necessary to deploy the site to GitHub Pages servers.

[Sharra-writes]

Okay! I've added a note to all the relevant Jekyll docs I could find, confirmed that information about implementing Jekyll with Actions and the .nojekyll file is available on our site (even if you probably have to use Google to find it without knowing the file name), and cleaned up the "who can use this feature" box since no one was reading it anyway. The note is also a reusable, so if anyone finds another article that could use the warning, it can easily be added. Hopefully all this makes your lives a little easier going forward. 🤞

[0xdevalias]

Hopefully all this makes your lives a little easier going forward. 🤞

Thanks for all your hard work @Sharra-writes !