+44 07967 557183

Running GitHub Pages using Jekyll Locally

If you use a GitHub Pages Site and want to run it locally for testing and development. You’ve come to the right place to learn how to get it up and running in a matter of minutes. Running Jekyll Locally on Windows

To run Jekyll locally on Windows there are a couple of necessary components.

Step 1 - Install Ruby Go here and download the latest version of Ruby for your machines architecture. http://rubyinstaller.org/downloads/ (2.3.3 was current at the time of writing this document)

Execute the installer and go through the steps of the installation. When you get to the screen, make sure to check the “Add Ruby executables to your PATH” box.

Step 2 - Install Ruby DevKit Jekyll has some dependencies which, out of the box, only provide raw source code. To make them into fully functional executables, you’ll probably need to install the Development Kit.

Go to the link below and download the DevKit archive that corresponds to your Ruby installation and system architecture. Choose the file marked as For use with Ruby 2.0 and above.


The download is a self-extracting archive. When you execute the file, it’ll ask you for a destination for the files. Enter a path that has no spaces in it. Something simple, like *C:\RubyDevKit*. Click Extract and wait until the process is finished.

Next, you need to initialize the DevKit and bind it to your Ruby installation. Open your command prompt and navigate to the folder you extracted the DevKit into.

cd C:\RubyDevKit

 Auto-detect Ruby installations and add them to a configuration file for the next step.

ruby dk.rb init

Now ensure the init command completed successfully.

ruby dk.rb review

 Now complete your installation of the DevKit by binding it to your Ruby installation.

ruby dk.rb install

Step 3 - Install Jekyll Ruby Gem To install Jekyll and all its default dependencies, launch a command prompt tool and enter the following command.

gem install jekyll bundler Step 4 - Install Jekyll Pagination Dependency Run this from a command prompt.

gem install jekyll-paginate Step 5 - Install Pygments Dependency Run this from a command prompt.

gem install pygments.rb

Step 6 - Create a new Blog or Clone the Repo of your existing Blog If you have pulled an existing Blog repo from Github pages, you may need to update your _config.yml file.

The files used for running Jekyll locally are a slightly newer version, so a couple of changes to the _Config.yml file are needed.

Change the line:

"highlighter: pygments"** to **"highlighter: pygments.rb"

Add the following to the bottom of the _config.yml file

# Gems
gems: [jekyll-paginate] 

Working with Jekyll Starting the Site Open a command prompt in the directory you cloned the repository to and run the following

jekyll serve

A development server will run at http://localhost:4000/

 Stopping the Site Simply press Ctrl +C in the same Cmd window where Jekyll is running

Building the site After adding the content, you will need to rebuild the site contents, run the below command.

jekyll build

Writing Blog Posts To write a Blog post, you need to write some Markdown in the folder _posts the site should automatically update the content, check the output in the console window.

To make an excerpt appear on the Home screen, make sure you include <!–more–at the end of your first paragraph. Otherwise the article will be fully expanded.

If this is the first time you are editing the blog, you need to set up your members profile in the _members directory, _layouts_members directory and edit _data\members.yml.

If you create new Tags in your article, you will need to update _data\tags.yml Also you need to create a .md file in the \tag\ folder to match you new tag, so that the content is generated correctly.