I’ve discovered Jekyll in fall 2016. It’s a simple static site generator which transforms your plain text and markdown documents into websites and blogs. Comparing to Wordpress (or other dynamic blogging engines), Jekyll doesn’t run any logic on the web server, as a result, you can host it on the simplest HTTP server and don’t worry about any vulnerabilities. All “dirty” job is done on your local work machine or CI server.

Despite such architecture, you still can add dynamic features like comments or search by using third-party services (e.g. Disqus, Google Custom Search). I really like the idea of ramping up functionality on top of a simple but flexible base, instead of cutting off complex universal engines.

Here’s shortened list of commands, settings, plugins, Liquid tags and filters which I frequently use while working with Jekyll.

Setting Up and Running

# Install Jekyll and Bundler through RubyGems
$ gem install jekyll bundler

# To be able to run Jelyll without prefixing it with bundle exec ensure that you do not
# have different versions of the same gems installed simultaneously on your machine
$ sudo gem update
$ sudo gem cleanup

# Create new Jekyll blog with default theme (minima)
$ jekyll new blog-directory

# After adding new dependencies to Gemfile and _config.yml execute `bundle`
# to download them
$ bundle
# or check updates availability for dependencies and install them
$ bundle update

# Run server. All changes will be automatically applied, except changes in _config.yml 
# (server restart is required to pick them up).
$ jekyll s

# Process and render draft posts
$ jekyll s -D

# Publish posts or collection documents with a future date
$ jekyll s --future

# Run production environment (with Google Analytics and Disqus turned on)
$ JEKYLL_ENV=production jekyll serve
# you can specify server host (to be able to test from other devices in same network) 
$ JEKYLL_ENV=production jekyll s -H 192.168.1.47

# Just build production html to _site directory (output path could be changed with -d argument)
$ JEKYLL_ENV=production jekyll build

# You can use multiple configuration files to override Jekyll options (e.g. use `_dev.yml` to 
# disable HTML compression while running development environment)
$ jekyll s --config _config.yml,_dev.yml

# And finally, of course, you can print help for Jekyll
$ jekyll —help
# or review help for specific subcommand
$ jekyll build —help

Configuration Settings

Most of the Jekyll command-line arguments can be specified in configuration YAML file. By default Jekyll loads _config.yml, but you can specify one or more custom configuration files with --config command-line argument.

You can create two separate configuration files for development and production. For instance, if you use octopress-minify-html plugin, it’s a good idea to skip HTML compression while building or running server for development purposes. To achieve it you can create separate _dev.yml file with the following setting:

env: dev

and run your serve or build command with --config argument:

$ jekyll s --config _config.yml,_dev.yml

Settings from _dev.yml will override corresponding values from _config.yml.

All settings from your configuration are available through your posts and pages via site object. Also, you can add any custom settings to your configuration file, which will be available through site object too. Third-party plugins often use this ability to configure itself.

YAML Front Matter

In the YAML Front Matter section you can set predefined variables or create custom ones for using them in Liquid tags within further down code and also in all included files and layouts that the current page or post depends on.

There are few predefined global variables: layout, permalink, published. Posts predefined variables: date, category, categories, tags.

---
layout: post
title:  "New Testshare Post with Comments"
date:   2017-02-04 11:17:29 +0200
permalink: welcome/
share: false
comments: false
sitemap: true
image:
  facebook: img/facebook.png
  twitter: img/twitter.png
---

To use these values in Liquid tags you should refer page or post objects:

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

You can set default values for your YAML Front Matter variables in _config.yml to avoid repeating of the same lines in all post files:

defaults:
  - scope:
      path: "" # all files within the project
    values:
      image:
        facebook: /assets/images/max-fb.png
        twitter: /assets/images/max-twitter.png
        width: 200
        height: 200
      share: true

Liquid Tags and Filters

Variables

{% assign integer = 10 %}
{% assign condition = false %}
{% assign string = "Hello World!!!" %}

Control Flow

{% if condition %}
  ...
{% elsif second_condition %}
  ...
{% else %}
  ...
{% endif %}

Iterations

{% for slide in site.data.about-slides %}
  <img src="{{ "/img/" | append: slide.image | relative_url }}">
{% endfor %}

Includes

The include tag allows you to include content from another file stored in the _includes folder. You can pass parameters to included piece of code from a parent file.

<!-- post.html -->
...
{% include slideshow.html slides=site.data.about-slides max-width=500 %}
...

<!-- slideshow.html -->
...
{% for slide in include.slides %}
  <img src="{{ slide.image }}" style="max-width: {{ include.max-width }}px;">
{% endfor %}
...

URL Filters

{{ "/assets/style.css" | absolute_url }}
Output: http://127.0.0.1:4000/jekyll/assets/style.css

{{ "/assets/style.css" | relative_url }}
Output: /jekyll/assets/style.css

{{ "Email info@liquid.com" | cgi_escape }}
Output: Email+info%40liquid.com

Markdown Extra Image with Caption

By default Jekyll uses kramdown as a Markdown processor, which is enhanced with features that are found in other Markdown implementations like Maruku, PHP Markdown Extra and Pandoc. For instance, it supports attribute list definitions with the help of which you can add attributes to block and span-level elements.

Let’s say you have following styles:

.center {
  text-align: center;
}

.thumbnail {
  border: 1px solid $grey-color-light;
  border-radius: 4px;
  padding: 4px;
  margin: 5px 0px;
}

.caption {
  display: block;
  font-style: normal;
  font-size: $small-font-size;
  color: $grey-color;
  line-height: 1.4;
  margin: auto;
}

You can use them to insert image with caption using next Markdown Extra text:

![Surprised ALF]({{ "/assets/images/surprised-alf.gif" | relative_url }} "Oops!"){:.thumbnail}
*I guess we'll have to order in*{:.caption}
{:.center}

Surprised ALF I guess we’ll have to order in

Note that you mustn’t have an empty line between the image and the caption. Also, attribute lists should immediately follow their blocks or elements.

Jekyll Plugins