Learn Jekyll Really Quick


  Posted on 26 Jun 2015
jekyll

This article is helping you learn the basics of Jekyll and setup your blog right now. The boring minutiaes which can easily learned when you use it is not mentioned at all.


What is it?

Jekyll is a software allowing you to setup and manage your blog with some HTML templates and snippets and nothing else.


Example

Here is an easy example to show the basic usage of Jekyll.

I suggest you star it on GitHub, unless you can remember it forever. You can fork or download it to work on it.


Explaination

Following is the file structure of the example.

.
+--_includes
|  +snappit.ext
|
+--_posts
|  +2013-01-01-title1.html
|  +2013-01-01-title2.html
|
+--_layouts
|  +default.html
|
+--_site
|
+--index.html It uses Liquid language to generate the pages. The "_site" directory contains the generated website.


#YAML Heads

We can see that nearly every file have something like the following in their heads.

---
layout: default
title: my post
---

They are called YAML. This defines some properties of the files for us to load when use them in jekyll projects.

You can define some properties of the project by writing YAML in “_config.yml”.


#Layouts

In the directory of “_layouts” are some HTML template files. They all have the keyword {{ content }}. It marks where the content of the file using the layout is to be inserted. You can write “layout: layout_file_name” in the YAML to set the layout of the file. Actually, the layout_file_name is a path and name relative to the directory of “_layouts”.


#Includes

In the directory of “_includes” are some “*.ext” files. They are the HTML snippets to include in other files. Use the following code to insert the snippets.

{% include file_name.ext %} The file name is actually a path and name relative to the directory of "_includes".


#Posts

In the directory of “_posts” are the articles in the blog. They can be written in HTML. Their names must be in the format of “yyyy-mm-dd-name.html”.


#Index

We need to include the list of our posts in “index.html” by the following code.

{% for post in site.posts %}
<p>
<a href="{{post.url}}">{{ post.title }}</a>Posted on {{ post.date | date_to_string }}
</p>
{% endfor %}

This is a loop generating the title and link of each post. We can have multiple HTML files or directories in this directory, just like a normal website’s structure including CSS and JavaScript. They will all be proceeded just like the index.


Build Command

In linux operating system, first cd to the directory contains the jekyll project. Then, type in the following command. Finally, check “http://127.0.0.1:4000/” in your browser. The index will be displayed.

jekyll serve