Creating a static Jekyll website with Github and Cloudflare Pages

Before I created my Thurmware Blog, I had three simple requirements in mind. First of all, the site had to be visually simplistic and uncluttered. Second, it had to offer customisable features that were easy to manage. Third and most importantly, it had to be free.

Many years ago I had previously used the paid-for and managed minimalist blogging site Silvrback, which at the time suited my blogging needs. While I’m glad to see it’s still around, it no longer suited my requirements and thus the search for a new setup began.

Regarding my third requirement (free hosting), I already had my eyes set on Cloudflare’s Pages service. The free 100,000 daily limit requests on Pages/Workers was more than enough for my needs. It also suited me as I had a number of domains registered or managed on Cloudflare, and I was already familiar with their features and services.

It was only when I was comparing Github Pages that I came across the static site generator Jekyll, which ticked off my other two requirements. I was sold!

From template to deployment on Cloudflare Pages – A simple step by step guide

While documentation exists for this scenario, it made sense to centralise and simplify the documentation here into easily digestible chunks. I also came across a number of stumbling blocks during my initial deployment, so I’ll also include some pointers for certain stages.

Note: This guide assumes you’ll be using a pre-made template. I also won’t cover content creation and other basic customisation options for your site as this is relatively straightforward and well documented elsewhere.

Step 1) Pick a template… Any template…

There are a number of great Jekyll templates available for varying requirements, but especially more so for blogging. Besides the actual HTML/CSS elements, they also contain the necessary Jekyll configuration files for testing and building our site.

For my requirements I chose the super minimalistic Sidey Template. Overtime I’ll gradually adjust this theme but for the time being I’ll be sticking with the default layout.

You can simply choose your template of choice on Github and fork the repo, then download locally using Git Clone.

Navigate to your downloaded repo and setup a new Git Branch in order to track changes.

Note: Some Jekyll templates contain features and plugins that are not supported on Github Pages, and possibly on Cloudflare Pages too. Make sure to review the Template’s Readme, as they often provide work arounds and/or alternatives.

Step 2) Check the current supported languages on Cloudflare Pages

Our Jekyll static site generator requires Ruby in order to both build and test our site locally. Our locally installed Ruby version also needs to be compatible with Cloudflare Page’s version.

Run the following command on your terminal:

$ ruby --version 

ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x64-mingw-ucrt]

Now check Cloudflare’s supported Ruby version here.

I didn’t have Ruby on my computer beforehand, and made the rookie mistake of blindly installing the latest version of Ruby which CF Pages didn’t support, so do check you have the right version of Ruby installed before continuing.

Step 3) Install Bundler

Bundler is a Ruby Gem that takes the information from our template’s dependencies file “Gemfile” and installs them locally. It’s the preferred method for tracking and installing your project’s Gems. Install Bundler with:

$ Gem install bundler

Step 4) Install Gems and serve Jekyll site

If you’ve not already done so, navigate with your terminal to the root of your locally downloaded repo and run the following commands:

$ Bundle install

This will install the Gems listed in our Gemfile. Once our Gems are installed, we can build and test our site locally using the following command:

$ Bundle exec jekyll serve

This will build and serve our site via http://127.0.0.1:4000.

From here you can navigate to your site and make sure that everything checks out.

You can also append arguments to our command, for example if you want to also view your unpublished posts, simply append --unpublished. More arguments can be found here.

Step 5) Push changes to repo

If you’re happy with your site, push it to your remote repo and merge the changes.

Tip: Consider adding your Jekyll site’s output folder “/_site” to your .gitignore file. Each time you deploy your site to CF Pages, Pages will generate a new /_site anyway, so tracking it in your Github repo serves little to no purpose.

Step 6) Create a new Cloudflare Pages instance and connect to Github

Login to your Cloudflare account, on the side bar navigate to “Workers & Pages” > Overview > Create.

Select the “Pages” tab and select “Connect to Git”. From here, you’ll need to grant Cloudflare Pages permissions to access “All Repositories”.

After connecting Cloudflare Pages to your Github account, you’ll be able to choose your relevant repo.

Receiving a 404 when connecting to Github?

If you receive a 404 on hxxps://github.com/apps/cloudflare-action/installations/new/permissions?target_id=XXXXXXXXX, it’s likely that your account has been flagged as spam. This is a common occurrence if you’ve recently created your Github account. It’s not at all obvious from this page and no verbose error message is provided. Simply create a support ticket and your account restrictions will be lifted.

Step 7) Configure Build & Deployments settings.

After selecting your Repo, you’ll need to configure the “Build & Deployments” settings.

On the “Framework Preset Dropdown” select “Jekyll”.

For our build command, use the following command:

bundle exec jekyll build

While the Cloudflare Jekyll documentation lists “jekyll build” as the default build argument, you’ll likely come across errors during your build process, causing the build to fail. So make sure to prepend “bundle exec”

Set your build output directory to Jekyll’s default directory:

Build Output Directory/: _site

Expand the “Environment variables (advanced)” section and add the following to both Production and Preview Environment (if applicable):

Variable Name           Value 

RUBY_VERSION            3.2.2

Ensure the RUBY_VERSION value matches that of the Ruby build version of your Jekyll site (Step 2). Alternatively, you can create a .env file to contain these settings.

Step 8) Deploy & Enjoy!

Once you’ve setup your Pages Instance, simply click “Save & Deploy” and your site build should be good to go! Once your site has been built successfully, navigate to your allocated *.pages.dev url to confirm it’s up and running.

You can also attach a custom domain to your Pages instance free of charge.

By default, your Cloudflare Pages will conduct a new build every time your Repo is updated, seamlessly updating your site to the latest commit. Make sure to check out the other settings available under your Pages Instance, and consider reviewing the other available Cloudflare features to further enhance your new Jekyll site.

Happy Blogging! 🥳