Creating a static site with Jekyll

This article explains how I created this site using Jekyll.

1. Installing Jekyll

My development environment is Linux Mint which is based on Ubuntu, so following commands will work for both. For other OS check the official Jekyll website.

Jekyll is based in ruby and uses gem to control its installation process, requiring the packages:

sudo apt-get install ruby
sudo apt-get install ruby1.9.1-dev

Once the ruby packages have been installed we can proceed to install Jekyll

    
sudo gem install jekyll

2. Creating a new Jekyll Project

A Jekyll project is based in several preconfigured folders and files. For this example we will go with the basics, for further information check Jekyll Structure. To create a new site use the sintax jekyll new {project directory name} that will create the following structure:

.
├── _config.yml
├── css
│   ├── main.css
│   └── syntax.css
├── index.html
├── _layouts
│   ├── default.html
│   └── post.html
└── _posts
    └── 2014-01-23-welcome-to-jekyll.markdown

To modify this default folder structure check Jekyll Configuration

3. Configuration

This is not strictly necessary because the Jekyll has a basic configuration by default. We will only add some global properties and configure the markdown editor to use ‘redcarpet2’

_config.yml

author: Jose Estudillo
markdown: redcarpet

DEPLOYS what is deployed and how

4. Page

Jekyll allow serveral ways to create a page, in this post I will focus on markdown.

page.md

---
#YAML declaration
layout: page_layout #the layout parameter will select which layout to generate the html associated to this file
title: Page Title
---
#Page Main Title

Text

In the YAML (after the first ---) declaration we usually declare parameter for the page that will be generated (title, author,…). In the markdown declaration (after the second ---) we will place the content. For further information check the official markdown documentation.

5. Layout

The layout will allow us to place the content generated in the markdown file in a good looking HTML.

 

{{% include header.html title="Given title" %}}

<p>{{page.title}}</p>

<div>{{content}}</div>

{% include footer.html %}

markdown generates concrete HTML for each of its elements so the idea is to style this specific format using CSS based on the wrapper of the content, besides this, markdown allows to use plain HTML. From the layout side Jekyll allows the use on is templates of liquid.

In every layout there are three global vars that are always defined:

• site: that refers to the information declared in _config.yml
• page: information related the the page itself
• content: refering to the content generated by markdown

6. Includes

To keep it simple we will go for a simple header and footer that we will place in

• _includes/header.html
• _includes/footer.html

to use import this files in a layout we will use the following codes

{% include header.html title="Constant String" value_from_a_variable=name_of_the_variable %}
...
{% include footer.html %}

Where the first part of the example shows how to pass parameters to an include. The parameter will be read as follows:

    {{include.title}}

7. Paginated index

Once you have reached a certain numbers of posts, pagination is a must. Jekyll allow you to paginate the post in to basic steps:

• First will require to configure the pagination extension in the file config.yml:

paginate: 5
paginate_path: ":num"

where paginate defines the number of post per page, and paginate_path will define how the page is shown in the URL.

• The second one will be define the Liquid/HTML code to navigate through the index pages, that contain the links to the different post, this must be defined in the file index.html:

{% if paginator.previous_page %}
  {% if paginator.previous_page == 1 %}
    <!-- /1 doesnt exist so you must be redirected to the root for the first page of the index -->
    <a href="/"/>
  {% else %}
    <!-- link to the previous page -->
    <a href="{{ paginator.previous_page }}"/>
  {% endif %}
{% else %}
  <!-- covers the case when there is no previous page -->
  <a href="#"/>
{% endif %}

<!-- show current / total number of pages -->
<span class="page_number ">{{ paginator.page }} / {{ paginator.total_pages }}</span>

{% if paginator.next_page %}
  <!-- link to the next page of the index -->
  <a href="{{ paginator.next_page }}"/>
{% else %}
  <!-- covers the case when there is no next page -->
  <a href="#"/>
{% endif %}
 

Apart of this, Jekyll also allow to navigate from a post to the next and the previous posts, this should be defined in the template for the posts:

{% if page.previous.url %}
  <a href="{{page.previous.url}}"/>
{% endif %}
{% if page.next.url %}
  <a href="{{page.next.url}}"/>
{% endif %}

8. Building the site

    jekyll build --watch

• Next Post →