Static website
with Jekyll

1st September 2014

At the beginning of the Internet, there were static sites: each web page was written “by hand” using a text editor, and then put online. The disadvantages are many, especially the need to duplicate the same changes on some pages (this is why it was sometimes really hard to maintain a website), to know HTML and to have his computer available to edit pages. The advent of CSS, which allows to separate actual content from its presentation format and to share it between the pages has not changed this fact (moreover, the inexistant interoperability between browsers and the poor support of CSS with Microsoft Internet Explorer, have delayed its use).

It was then that appeared dynamic sites: the different programming languages, ​​running on the server side, such as PHP, helped the rise of CMS, which made possible to create sites and change their content directly from a browser, thus allowing the emergence of sites, blogs, forums accessible to the greatest number. This is for example the case of Spip, Dotclear or WordPress. However, these systems are not without disadvantages:

For a couple of years, static websites has come back into favor with the emergence of the static website generators. With simple text files, a program generates a website made entirely from static pages you just have to host. Security problems are thus virtually non-existent, it is possible to host your website on a very modest server or rather the opposite, to get excellent performances and handle huge increases in workload using a CDN like Cloudflare or Cloudfront (ways to host a static website on Amazon S3 and Cloudfront are explained in “Static website with Cloudfront).

In addition, it is possible to follow the changes and to work collaboratively thanks to git, to write the articles online and to generate the website on the fly with services like GitHub and Prose, or to have a commenting system with Disqus.

This article will show how to install (I) and use (II) the Jekyll website static generator to create and modify a simple website.

First website with Jekyll

Installation of Jekyll

Directly install the last stable version of Ruby, or RVM, then simply launch:

gem install jekyll

On Windows, it is less easy to install Jekyll; however, Julian Thilo wrote a very detailed guide about how to do it.

Creation of a new website

The command jekyll new mysite will create the source code of a working website in the mysite folder. In this folder, you can generate the website with jekyll build. The output can then be seen in the _site/ folder.

With a single command, it is possible to generate the website and create a local host in order to watch the produced website: use jekyll serve in order to get your website available on http://localhost:4000. You can also automatically regenerate the website each time you change something in the source code (however, this option doesn’t detect the changes provided in _config.yml) with jekyll serve -w, which will be by far the most useful command when you’ll start to play with Jekyll.

Tree structure

Jekyll uses several folders:

The tree structure may then looks like:

mysite/
        _includes/
        _layouts/
                default.html
                page.html
                post.html
        _posts/
                2014-08-24-static-website-with-jekyll.md
        assets/
                style.sass
                script.js
                favicon.ico
        index.html
        rss.xml
        _config.yml

You can add any folder or file in your website folder. If they don’t start with an underscore, Jekyll will generate them on the same location.

Using Jekyll

Now that the first website is created, we will see how to make it evolve, how to write articles and use metadata.

In order to create an article, juste create in _posts folder a file with a name with the following format: yyyy-mm-dd-post-name.md (it is also possible to create articles in the folder _drafts, without any date in the file name: thus, it will create drafts invisible in the posts list but available with their URL). This file is divided into two sections: the frontmatter where the metadata are stored, and the content of the article.

Frontmatter and metadata

The frontmatter allows us to declare metadata, which will be called or tested in the website (see below). It is set into the top of the file, under the following format:

---
layout: default
title: My title
---

Only the layout variable is required: it defines which file in _layouts/ Jekyll should use to build the page. It is also usual to define a title variable in order to provide a title to our article (some variables are reserved by Jekyll with a particuliar behaviour: permalink for exemple specifies the final URL of a file).

It is also possible to define default variables, declared once for all or parts of the articles. For instance, instead of declare layout: default in each article stored in _posts/, you may declare it once in _config.yml:

defaults:
  -
    scope:
      path: "_posts"
    values:
      layout: "default"

Writing articles with Markdown

By default, Jekyll use Markdown. The purpose of this language is to provide a very simple syntax to replace the most commons HTML tags. For example, *italic* gives “italic” and **bold** gives “bold”. It is however still quite possible to use HTML in posts.

From its second version, Jekyll uses Kramdown which add many features like the possibility of giving CSS classes to elements, footnotes, definition lists, tables…

Using metadata

Any metadata “variable”, declared in the frontmatter or as a default, can be called anywhere in the website, with the tag {{ page.variable }}, which returns its value.

It is also possible to do some tests:

{% if page.variable == 'value' %}
    banana
{% else %}
    coconut
{% endif %}

We can also, for example, make loops on each article satisfying some conditions:

{% assign posts=site.posts | where: "variable", "value" %}
{% for post in posts %}
    {{ post.lang }}
{% endfor %}

Although the syntax may not be very elegant to use, the large number of available variables, plus the custom metadata, combined with the filters et commands, may become highly effective.


And much more…

This article doesn’t claim to be more than a very short introduction to Jekyll. To go further, read the Jekyll excellent documentation first, regularly updated, and the numerous references you will find on the web.

You may also read three other articles written on this website about Jekyll:

Lastly, browsing website using Jekyll source codes (feel free to browse the source code of this website to find out how it works), in order to find inspiration, can only be a good idea.


Published on the 1st September 2014 by Sylvain Durand.