Skip to content

Migrating a Jekyll-based site from GitHub Pages

Last reviewed: about 3 years ago

In this tutorial, you will learn how to migrate an existing GitHub Pages site using Jekyll to Cloudflare Pages. Jekyll is one of the most popular static site generators used with GitHub Pages, and migrating your GitHub Pages site to Cloudflare Pages will take a few short steps.

This tutorial will guide you through:

  1. Adding the necessary dependencies used by GitHub Pages to your project configuration.
  2. Creating a new Cloudflare Pages site, connected to your existing GitHub repository.
  3. Building and deploying your site on Cloudflare Pages.
  4. (Optional) Migrating your custom domain.

Including build times, this tutorial should take you less than 15 minutes to complete.

Before you begin

This tutorial assumes:

  1. You have an existing GitHub Pages site using Jekyll
  2. You have some familiarity with running Ruby’s command-line tools, and have both gem and bundle installed.
  3. You know how to use a few basic Git operations, including add, commit, push, and pull.
  4. You have read the Get Started guide for Cloudflare Pages.

If you do not have Rubygems (gem) or Bundler (bundle) installed on your machine, refer to the installation guides for Rubygems and Bundler.

Preparing your GitHub Pages repository

Your existing Jekyll-based repository must specify a Gemfile (Ruby’s dependency configuration file) to allow Cloudflare Pages to fetch and install those dependencies during the build step.

Specifically, you will need to create a Gemfile and install the github-pages gem, which includes all of the dependencies that the GitHub Pages environment assumes.

Create a Gemfile
cd my-github-pages-repo
bundle init

Open the Gemfile that was created for you, and add the following line to the bottom of the file:

Specifying the github-pages version
gem "github-pages", "~> 215", group: :jekyll_plugins

Your Gemfile should resemble the below:

# frozen_string_literal: true
source "https://rubygems.org"
git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
# gem "rails"
gem "github-pages", "~> 215", group: :jekyll_plugins

Run bundle update, which will install the github-pages gem for you, and create a Gemfile.lock file with the resolved dependency versions.

Running bundle update
bundle update
# Bundler will show a lot of output as it fetches the dependencies

This should complete successfully. If not, verify that you have copied the github-pages line above exactly, and have not commented it out with a leading #.

You will now need to commit these files to your repository so that Cloudflare Pages can reference them in the following steps:

Commit Gemfile and Gemfile.lock
git add Gemfile Gemfile.lock
git commit -m "deps: added Gemfiles"
git push origin main

Configuring your Pages project

With your GitHub Pages project now explicitly specifying its dependencies, you can start configuring Cloudflare Pages. The process is almost identical to deploying a Jekyll site.

To deploy your site to Pages:

  1. Log in to the Cloudflare dashboard and select your account.
  2. In Account Home, select Workers & Pages > Create application > Pages > Connect to Git.
  3. Select the new GitHub repository that you created and, in the Set up builds and deployments section, provide the following information:
Configuration optionValue
Production branchmain
Build commandjekyll build
Build directory_site

After you have configured your site, you can begin your first deploy. You should see Cloudflare Pages installing jekyll, your project dependencies, and building your site, before deploying it.

After deploying your site, you will receive a unique subdomain for your project on *.pages.dev. Every time you commit new code to your Jekyll site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to preview deployments on new pull requests, so you can preview how changes look to your site before deploying them to production.

Migrating your custom domain

If you are using a custom domain with GitHub Pages, you must update your DNS record(s) to point at your new Cloudflare Pages deployment. This will require you to update the CNAME record at the DNS provider for your domain to point to <your-pages-site>.pages.dev, replacing <your-username>.github.io.

Note that it may take some time for DNS caches to expire and for this change to be reflected, depending on the DNS TTL (time-to-live) value you set when you originally created the record.

Refer to the adding a custom domain section of the Get started guide for a list of detailed steps.

What’s next?