Learn The Basics of Jekyll

Note, May 2016: As of now, this tutorial is intended for Mac users. For guidence on mac OS installation check here

About Jekyll

What Is Jekyll and What Does It Do?

Jekyll is a static site generator used to create websites that exist as a directory of files. Because Jekyll is used to create static sites instead of dynamic ones, there are some helpful advantages that come along with using it:

  1. Static sites do not require an extensive back end, which allows for quicker and simpler development.

  2. Due to the lack of server side scripts, the security of a jekyll site is far more apparent than that of a dynamic page. Because all of the files are created and collected upon launch there is little room for hacker threat to the sites infrastructure.

There are also some Disadvantages to using a static site as well

  1. Because static sites cannot pull data from a standard database, the content within the site will always need to be edited manually. This requires some programming experience on the developer's end in able to edit content.

  2. In addition to manually editing files in able to make changes, and depending on your changes multiple files may need to be edited. Just as the step before, YMMV depending on your programming experience.

For a visual representation of the power of Jekyll, here are some sites that were created with it:

As you can see from both the Tom Preston-Werner and Rasmus Andersson pages, but most notably the Tom Preston-Werner page, Jekyll functions primarily as a blog site with the ease of displaying and creating pages as posts.

Setting Up Jekyll and Jekyll Environment

a. Jekyll Installation

Installing and launching Jekyll will all be done from the terminal. All of the instructions here can also be found on the official jekyll documentation page.

After initially opening your terminal you should be in your user directory, displaying all of your documents when listing all of the files.

from within your user directory, run this command in able to begin the jekyll install

gem install jekyll

IMPORTANT: in able to install these packages you will need root permissions, if your account does not have these permissions, you can run these commands along with the ‘sudo’ command. For example: 'sudo gem install jekyll'

b. Other Installations

You will also need to install the jekyll bundler by running the command:

gem install jekyll bundler

In able to access and edit files within your jekyll project, you will need a text editor. Any text editor will work, but I recommend the free text editor sublime text 3.

Lastly, you will need to have Ruby installed. Luckily, all mac devices come preinstalled with Ruby so no installation should be needed. However, if you do need to install Ruby, you can do so here.

c. Getting Started With Jekyll

In able to begin building our jekyll site, we must first create the project directory. Luckily, this is can be done with a simple command from within the terminal. From the terminal, navigate to your Desktop and run the following command to create a project entitled ‘myjekyllsite’:

Jekyll new myjekyllsite

Now that we have our project directory created, navigate into it from within the terminal and launch it using the following command:

Bundle exec jekyll serve

Now that we have our project up and running on a local server we can take a look at the active project by entering the URL address “localhost:4000” within any browser of your choice while the application is running. By default, all Jekyll projects run locally on port 4000, hence, the address “localhost:4000”. After entering the URL to your localhost, you should see a page similar to this one

In able to stop your project press the following key combination in the terminal (at the same time):

control + c

While editing our Jekyll project files, front end changes to our code will be able to take effect immediately upon save and can be viewed upon reloading the page. You can see if these changes have been successfully implemented by viewing the active log on at the terminal. This log will remain active and up to date as long as the project is running. Any changes to the .config file will require a server restart in able for the changes to take effect.

Premade Files

To view the project directory you can either open it directly from the desktop or by using our Sublime text editor. For the sake of convenience, we will be viewing our project inside of the Sublime text editor.

After opening the project within Sublime, or any other text editor of your choice, you should be able to view all of the files within the project. Various version updates to Jekyll may often change which files are included with your new project, so we will just go over the most relevant files.

From within your project folder, you should have the files listed below. Click on each file to find out more about it.






Additional Files

Note, While adding files to the directory, it is important to remember to follow the spelling as shown below. This includes having the underscore in front of specific folders names.

In addition to the pages provided with our default creation, we will also need some additional folders to the project directory as well. In able to add files into the project folder, simply bring up the right click menu on the 'myjekyllsite' folder and 'new folder'.

Below are the files that need to be added, click on each box to learn about individual files.




Before moving on throughout this tutorial, make sure to delete the 'index.md' file and replace it with an 'index.html' file. This will allow us to use HTML on our index file.

Creating Your First Page

Note, due to the nature of how the steps for this section were laid out, it would be best to restart/start your project server after all of the steps in the 'Ceating Your First Page' section have been completed. Specifically, after creating your content and before styling your page.

Front Matter and Content

A Jekyll page consists of two main parts, the front matter and the content.

Front Matter

Very much like the config.yml, in the sense that it can control settings on specific pages. The difference, however, being that while a config.yml file can control settings for multiple elements across several pages, the front matter of a Jekyll file can only control the settings for the page in which it is located.


The content of a Jekyll page contains all of the body text, everything in between the headers and footers.

At this point, you should have already replaced the 'index.md' file within the directory with an 'index.html' file. If not, then simply delete the “index.md” file from your Jekyll project and add a new one by the name of “index.html” into the root directory.

Creating The Front Matter

The front matter in this tutorial will consist of only a layout, and will implement custom paths in a further section. On your empty Index.html page, apply this code:

layout: home
Note, when applying layouts to a page through this matter, the extension '.html' does not need to be applied to the name just as above.

This code will allow us to pull a layout from the “_layouts” page as our layout. Next, after telling our file to pull the layout, we must now create one in able for our page to have something to load.

Creating The Layout

From within our _layouts folder, create a file by the name of “home.html”, and then open it in our text editor.

Because our layout file will dictate how our page is presented, we will need to create the outline of our layout for jekyll to fill in upon load. The code below shows how we will structure our home page layout. Copy and paste this into your empty home file in the _layouts directory.

<!DOCTYPE html>
	{% include header.html %}
	{% include head.html %}
	<div class="page-wrap">


	<footer class="site-footer">
		{% include footer.html %} 

From this code snippet we can see that our home page will include both the header and header files, the page content below that, and then the footer last.

Now to create the Header, Head, and Footer files for this layout to include. Within the '_includes' folder, add these files below with the names exactly as they are shown. Click on the individual names to receive the code to copy and paste into each corresponding file.




Now that we have all the includes for our home page, let’s go on to creating the content.

Creating The Content

Luckily, the harder part of creating the home page is behind us, and now that we have our layout set up, we can simply type up some content for our page.

Underneath your front matter on the “index.html” file, go ahead and type up a sentence or two of raw text into the specified location below as an introduction to the site, just as if you were typing in a Microsoft Office document.

Even though simply placing raw text within a .html file may seem wrong at first, as you will see, it is very much doable. In addition to being able to process raw text, jekyll will also accept html code in able to better organize and style your page just as any other html file. For example, <div> and <p> tags WILL WORK here.

Something to keep in mind when creating pages is that every page will need a layout, and if a layout is not specified, our will not be applied and none of the includes that we have within our layout would be activated. After a layout has been created, it can be applied to a page by telling it to do so from within the front matter of that specific page.

Upon relaunching, your page should look like this.

Styling Your Page

In able to keep our directory organized, make a file called “main.css” within the css folder of our project, and just as before, I will provide you with some code in able to expedite this step, all you will have to do is copy the code snippet below and paste it into the main.css file you just created.

	overflow-y: hidden;
  text-align: center;
* {
  margin: 0;
html, body {
  height: 100%;
.page-wrap {
  min-height: 100%;
  /* equal to footer height */
  margin-bottom: -142px; 
.page-wrap:after {
  content: "";
  display: block;
.site-footer, .page-wrap:after {
  height: 142px; 
.site-footer {
  background: #F8F8F8;

.site-footer p{
  text-align: center;
  padding-top: 2%;

After styling your page, it should look like the image below. With the main.css file attached to your head, it will allow you to edit any element within the web page.