bemycto.com: Building a blog with Jekyll in 5 points – Part 2: Templates

bemycto.com: Building a blog with Jekyll in 5 points – Part 2: Templates

This post is the continuation of a previous article: Building a blog with Jekyll in 5 points – Part 1: Presentation. Please be sure you read it first.
For the second part of this Building a blog with Jekyll series, we’ll take a look at the Liquid template system. It’s quite cool and powerful, I’m sure you will love it.

Basic overview
Liquid is a template engine written in Ruby and created by Shopify for theming purpose. As it’s a powerful library, Jekyll uses it as its template engine.

Liquid is based on three concepts:

Objects and variables that you can output, assign and modify
Filters that allow you to transform your objects and variables data before outputting
Tags that change template flow and do complex stuff
Jekyll provides a lot of objects, filters, and tags. Using them, you can customize your website with few efforts.

Output data
First thing first, we need to output our data. We’re assuming our page has a page.title property which is equal to My awesome Title.

If we want to display this in an h1 tag, we can add this in our template:

{{ page.title }}

Don’t worry about HTML escaping: Liquid does the job for us. If you want to display raw data, for example if you have HTML tags in your title and you’re absolutely sure that this data is safe. You can use this instead:

{{{ page.title }}}

These are the basics of Jekyll templating. Now, we’ll take a look at the filters.

Filters
Filters help you transform your data in a convenient way. For example, imagine we’re sticking to the Ruby On Rails paradigm Convention over configuration.

We decided that using a slug of the title we can find its associated picture using this pattern:

/img/posts/${article_slug}.jpg
We can simply use the slugify filter to make this possible:

{{ page.title}}
Simply using the | operator we can process our data with the given filter to transform them. That’s incredibly powerful, and there is a ton of filters available. Don’t worry about the site.baseurl, we’ll talk about this in the part 3.

If you want a complete list of available filters, take a look at the documentation.

Tags
Tags are a powerful way to change your template flow. Typical tags are if blocks, for loops.

Tags are called like this:

{% my_tag and_some_optional_params %}
One of the most useful to reuse content is the include tag, especially combined with the for tag. For example:

{% for post in site.posts %}
{% include post_preview.html current_post=post %}
{% endfor %}
The file named _includes/post_preview.html will be loaded, and can access the include.post value. For example to only display post title:

{{ include.post.title }}

If you want a complete list of available tags, you get it, the documentation is here fo this.

Customization
If you want to go further and create your own filters and tags, Jekyll allows it. We won’t cover this topic here, but you can find a lot of plugins that add new filters, tags and a lot of cool stuff.

For example in The WebTechie Review, I use two plugins:

One for generating the tag cloud
One that modifies categories permalinks to slugify them
Wrapping up together
Summing it all up, here is a quick sample of how we can display a posts list:

# Content of the index.html file

My site posts

{% for post in site.posts %}
{% include post_preview.html current_post=post %}
{% endfor %}
The empty metadata block (surrounded with 3 dashes) is mandatory for Jekyll to parse your file. Without it, it will include it as plain text without parsing.

# Content of the post_preview.html file

{{ include.current_post.title }}

{{ include.current_post.title }}
{{ include.current_post.excerpt }}
{{ include.current_post.content | number_of_words }} words
{{ include.current_post.date | date_format_to_string }}
Given the following post:

# Content of _posts/2015-05-23-my-post.md

title: My post
date: 2015-05-23

This first paragraph will be the excerpt property. Please don’t truncate it without stripping tag before.

This second paragraph will only be displayed in the content property.
Will generate the following HTML:

My site posts

My post

My post

This first paragraph will be the excerpt property. Please don’t truncate it without stripping tag before.

27 words
2015-05-23 00:00:00 +0200
Pretty powerful, isn’t it?

Next time…
Now it could be a little clearer… But I imagine you have still many questions:

What are those variables like site.posts and such?
How can I build a real website using Jekyll?
How can I deploy it in production?
These three points are going to be explained in the next parts. If you have a question, please leave a comment 🙂

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s