GitHub Pages Gem

GitHub Pages Gem is a Ruby tool that bootstraps and maintains a local Jekyll build environment matching the exact dependency versions used by GitHub Pages.

What is the GitHub Pages Gem?

GitHub Pages Gem is a Ruby Gem, developed by GitHub, that installs Jekyll and its dependencies at versions pinned to those used by GitHub Pages' build servers. It takes a project's Gemfile as input, adds the gem, and outputs a local environment where jekyll build and jekyll serve behave like the live site build. It runs on any system with Ruby and Bundler version 1.14 or newer.

Key Features

• Version locking — The gem explicitly versions both the Ruby interpreter and dependencies like Kramdown, Liquid, and RedCloth so local builds match GitHub Pages' build environment.
• Command-line tools — github-pages versions lists dependency versions in a table or valid Gemfile format; github-pages health-check checks DNS configuration for custom domains.
• Docker support — Build a gh-pages image with make image (or make image_alpine for a smaller Alpine-based image) and serve a site on port 4000 without installing Ruby locally.
• Plugin whitelist bypass — Prefix jekyll build or jekyll serve with DISABLE_WHITELIST=true to run non-whitelisted plugins during local preview only.
• Bundler integration — Add gem 'github-pages', group: :jekyll_plugins to a Gemfile, run bundle install, and Jekyll is available without separate installation.
• Simple updates — gem update github-pages or bundle update github-pages brings in the latest Jekyll and dependency versions.

Who is it for?

• Jekyll site developers who publish with GitHub Pages and want a local preview that matches the deployed output.
• GitHub Pages users managing custom domains who need to run github-pages health-check to catch DNS misconfigurations before going live.
• Plugin authors who want to test non-whitelisted Jekyll plugins locally by enabling DISABLE_WHITELIST=true during a local build.

What can you do with it?

• Preview your site locally: Run jekyll serve after installing the gem to see exactly what GitHub Pages will render, with no version drift.
• Check dependency versions: Run bundle exec github-pages versions to see the pinned versions of Jekyll, Kramdown, Liquid, and more, or pass --gemfile to output them in Gemfile format.
• Build a Docker container: Use the Makefile to create a gh-pages image and serve any Jekyll site from a container without installing Ruby or gems on your host.

How does it work?

1. Add gem 'github-pages', group: :jekyll_plugins to your project's Gemfile.
2. Run bundle install; the gem installs Jekyll and all versioned dependencies.
3. Build with jekyll build or preview with jekyll serve, optionally overriding the plugin whitelist with DISABLE_WHITELIST=true for local testing only.

Pricing

The GitHub Pages Gem is free and open source, distributed under the MIT License.

FAQ

How do I install the GitHub Pages gem?

Add gem 'github-pages', group: :jekyll_plugins to your Gemfile, make sure Bundler is newer than version 1.14 by running gem update bundler, then run bundle install. You don't need to install Jekyll separately.

What does github-pages versions do?

It shows the exact versions of Jekyll and its dependencies pinned by the gem, in a table format. Passing the --gemfile flag outputs the same list in a format you can paste directly into a Gemfile. Live production versions are also published at pages.github.com/versions.

Can I use non-whitelisted Jekyll plugins with this gem?

Yes, but only locally. Prefix jekyll build or jekyll serve with DISABLE_WHITELIST=true to allow any plugin listed in your site's gems configuration. This option does not affect the build that happens when GitHub Pages publishes your site.