Create a blazingly fast website and blog with Jekyll - the lightweight, static site generator written in Ruby.


Pre-Requisites:

  • Ruby programming language installed and up to date.
  • Basic knowledge of programming, HTML and CSS

Introducing Jekyll

Jekyll is an open source Ruby gem which makes it easy for you to create and maintain static websites and blogs. But why would you create a static website over a dynamic one? Well, static websites have less moving parts and do not require a database. Your pages are delivered straight from the server, with minimal load on the CPU, which results in fast response times for your users.

Jekyll is 'blog aware' by default and has many features which makes it competitive with popular blogging platforms, such as custom permalink styles and categorising blog posts automatically. If you decide Jekyll is for you, then there are even tools available to help you migrate your existing blog into one created with Jekyll.

Despite Jekyll itself being written in Ruby, no knowledge of Ruby syntax is required to create a site. However, it is possible to modify Jekyll or create custom plugins using the Ruby language if you choose to do so.

Jekyll was used to build Phonics.io, an interactive educational site to help people read and speak better English.

phonics.io
Phonics.io, Read and Speak better English

Ready to learn how to use Jekyll? Let's Begin.

Step 1) Installation

Before you can use the Jekyll gem, you first need to install the Ruby programming language. It is recommended to use Ruby version 1.9.X or greater, as these versions come bundled with the RubyGems library, which is required for installing Jekyll. Ruby works on most operating systems, but Linux and OS X have better compatibility. Using Windows may cause you some additional problems. This tutorial will be written with the presumption that you are using either Linux or OS X.

Once Ruby is installed, you can run the following command in your terminal to install Jekyll:

        $ gem install jekyll

Step 2) Create a new Jekyll project
We are now ready to create our first Jekyll project. We do this by using the following command in the terminal:

        $ jekyll new jekyll-tutorial

This will create a new folder called 'jekyll-tutorial', which contains all the files required to get your started on your website.

Step 3) Exploring the project structure
Once you have ran the command to create a new Jekyll project, you should open the 'jekyll-tutorial' folder inside of your favourite text editor. You will see the following project structure:

        ├── about.md
        ├── _config.yml
        ├── css
        │   └── main.scss
        ├── feed.xml
        ├── _includes
        │   ├── footer.html
        │   ├── header.html
        │   └── head.html
        ├── index.html
        ├── _layouts
        │   ├── default.html
        │   ├── page.html
        │   └── post.html
        ├── _posts
        │   └── 2015-03-17-welcome-to-jekyll.markdown
        └── _sass
            ├── _base.scss
            ├── _layout.scss
            └── _syntax-highlighting.scss

Here is a brief overview of some of the important files and folders:

_includes folder - The _includes folder is where users can add snippets of HTML which can be reused elsewhere in the project.
_layouts folder - Layouts are HTML files which contain the default look and feel for your website. These layouts can be used by new pages and posts.
_posts folder - This is where blog posts are kept. These blog posts can be Markdown or HTML files.
_sass folder - SASS is supported in Jekyll by default. SASS files in this folder will be compiled by Jekyll. Using SASS is entirely optional, and it can be switched out for conventional CSS files in the css folder.
_config.yml file - The config file is where you can access many advanced options for Jekyll. It is worth learning what can be changed inside the config file, but for the purpose of this tutorial we will stick with the defaults.

Step 4) Building and serving your website on localhost:
In order to be able to test the website on our development machines, we first need Jekyll to build and run a local server. We do this by typing in the following command into the terminal:

        $ jekyll serve

After Jekyll has completed building, it will prompt you to open your web browser and navigate to http://localhost:4000 to see the website in action. You should take some time to navigate around the website, and get a feel for how the pages are currently linked together. This should help you become more familiar with the project structure.

Once you are back inside your text editor, you will notice that Jekyll has created a new folder called _site. This folder is where Jekyll has parsed the project files, and outputted a compiled version of your website. This compiled version is what is served to the web browser. The _site folder and all of its contents are recreated every time you make changes to your project, so it is not recommended to edit these files directly.

Step 5) Understanding Posts:
Jekyll is perfect for creating a blog. By default, any Markdown files added to the _posts folder are presumed to be blog posts. If you go inside of the _posts folder, you will see a file which uses the following naming convention:

        yyyy-mm-dd-the-page-title.md

This file name convention is very important for two reasons. Firstly, Jekyll uses the date prefix to know how to order the blog posts. Secondly, it uses 'the-page-title' part of the file name as the URL for the blog post. Any new blog posts should follow this naming convention.

Now, let's open up the first file inside the _posts folder with your text editor.

You will notice that at the top of this file (and many other files in our Jekyll project), that there are some variables which are encapsulated by a pair of three hyphens:

        ---
        layout: post
        title:  "Welcome to Jekyll!"
        date:   2015-03-18
        categories: jekyll update
        ---

This syntax is what is referred to as YAML Front Matter. This Front Matter is used by Jekyll to determine whether a file should be parsed or not. When building your website, Jekyll reads the variables inside of this Front Matter and determines what to do with them.

One important variable for post files is the 'layout' variable. This is used to specify which HTML layout to use from the _layout folder when generating the Markdown file as static HTML. You will see that the file created for us uses the 'post' layout. Later in the tutorial we will take a look at the _layout folder in detail.

Adding a new blog post is as simple as creating a new Markdown file which follows the naming convention, and adding the YAML Front Matter at the top of the file. You can then add the content of your blog post using Markdown syntax.

Step 6) Understanding Pages:
Pages are static HTML files which are not categorised as blog posts. Pages do not have a strict naming convention, and they can be placed in any folder, except for _posts.

One example page created for us is the 'index.html' file located in the root directory of our project. Open this file in your text editor, and let's take a look at its syntax.

You will notice that this index page uses Front Matter in a similar way to the example blog post we looked at. You can see that the index.html file uses the 'default' layout:

        ---
        layout: default
        ---

You will also notice that there is some syntax on this page which does not look like standard HTML. These are Liquid templates, and they are used to add programming functionality to Jekyll websites. Let's take a look at the Liquid syntax on the index page:

        <ul class="post-list">
            {% for post in site.posts %}
            <li>
                <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>

                <h2>
                    <a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a>
                </h2>
            </li>
            {% endfor %}
        </ul>

We can see that there is an unordered list with a for loop inside of it. The for loop is cycling through all of the 'site.posts'. In Jekyll, 'site' is a variable for your website. Using 'site.posts' gives access to all of the blog posts in the _posts folder. So, we know that this for loop is cycling through all of our existing blog posts and doing something with them.

You will also see that the code is accessing 'post.date' and 'post.title' variables. These are taken from the Front Matter of each blog post. The 'post.url' is generated by Jekyll, but it is set by the naming convention we used for the files in the _posts folder.

So to sum up this code, we can see that this for loop is going through each of our blog posts and displaying their title, date, and URL inside an HTML unordered list.

You can read more about variables in the Jekyll documentation.

Step 7) Understanding Layouts:
We have seen both pages and posts referring to which layout they should use, but we have not yet looked at a layout file. Let's open the 'default.html' file in the _layouts folder:

        <!DOCTYPE html>
        <html>

          {% include head.html %}

          <body>

            {% include header.html %}

            <div class="page-content">
              <div class="wrapper">
                {{content}}
              </div>
            </div>

            {% include footer.html %}

          </body>

        </html>

This file contains most of the basic HTML that is required for our pages to render correctly in a web browser. This includes the , as well as the and tags. We can see that there are also two different types of Liquid tags on this page. There is one 'content' tag, and three 'include' tags.

The {{content}} tag is actually a special Jekyll variable. This is where the content of our pages and posts are injected if they are referring to a layout inside of their Front Matter.

The {% include %} tags are used to insert HTML snippets from the _includes folder. We will look at these includes in the next step of the tutorial.

One great feature is that layouts can be used by other layouts. We can see this in the 'page.html' and 'posts.html' layout files. They both reference 'default.html' in their Front Matter. This is useful, as it prevents us having to rewrite the generic HTML code each time a new page needs a slightly different layout.

Step 8) Understanding Includes:
As mentioned previously, includes are small HTML snippets which can be reused throughout our website. We saw in the previous section that the default layout used a total of three includes. These were the 'footer.html', 'head.html' and 'header.html' files. You can find these files inside of the _includes folder.

Open the head.html file inside of your text editor:

        <head>
          <meta charset="utf-8">
          <meta http-equiv="X-UA-Compatible" content="IE=edge">
          <meta name="viewport" content="width=device-width, initial-scale=1">

          <title>{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}</title>
          <meta name="description" content="{% if page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">

          <link rel="stylesheet" href="{{ "/css/main.css" | prepend: site.baseurl }}">
          <link rel="canonical" href="{{ page.url | replace:'index.html','' | prepend: site.baseurl | prepend: site.url }}">
          <link rel="alternate" type="application/rss+xml" title="{{ site.title }}" href="{{ "/feed.xml" | prepend: site.baseurl | prepend: site.url }}" />
        </head>

When Jekyll builds your website, this code will replace the include tag on the default layout file.

You may have noticed that this include file references the 'page.title' variable, as well as many other variables. When Jekyll is building, it parses all of the files in the project and ensures that all of these variables are populated with the correct values.

Step 9) Hosting your website:
There are many different options when it comes to deploying your Jekyll website. You can use the contents inside the _site folder and host that directly on your own server. You could also host these files on a content delivery service, such as Amazon S3. These methods, and many more, are covered in detail on the Jekyll documentation for deployment methods.

One of the best ways is to host your Jekyll website on GitHub Pages for free. You can even specify a custom domain. Despite being free, the GitHub Pages hosting is fast and reliable. I used this method to host phonics.io. You can view the repository for phonics.io here.

Further reading
This tutorial hopefully covered all of the basics required to understand how Jekyll works. If you like the idea of using Jekyll for your next website or blog, you should read the in-depth documentation on the Jekyll website.

If you are looking for an example of Jekyll using SASS, I created a starting template which utilises bootstrap-sass, the officially supported SASS-powered version of Bootstrap. You can view the project's repository here.