What is Jekyll?
06 Jul 2017What is Jekyll and how do I get started
Jekyll is a tool for generation of static sites. By static, we mean that there is no server-side scripting required and content is more or less fixed. Jekyll is written in Ruby. Jekyll is also blog-aware, which means that it is easy to create and manage blogs posts since your main focus is on content. As the site says,
Jekyll takes a template directory containing raw text files in various formats, runs it through a converter (like [Markdown](https://daringfireball.net/projects/markdown/)) and our [Liquid](https://github.com/Shopify/liquid/wiki) renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server.
** Installing and Themes ** So why use Jekyll? Why not create a website from scratch? The answer is that Jekyll provides numerous templates which are easy to modify. Thus, it saves you the time and effort to reinvent the wheel, starting with HTML and CSS. Moreover, Liquid and Markdown combined, make it very easy to achieve a lot of tasks like tagging, summary displays, etc. The theme that this site is based on is called Hyde.
So now know what Jekyll is. But how do you use it to create a site, perhaps like this one? Installation insructions for Jekyll are on their here. In case you want a more detailed version, I would point you to a wonderful tutorial that I myself refered to. Admittedly, using jekyll from scratch will not give you too much. You’d still have to style it using some CSS. This is where themes come in. You can pick a theme that appeals most to you. While picking, you can decide whether you want style or functionality. I’ll give you an example of what I did with Hyde.
I picked Hyde because I liked the split screen format that it had with one side being a navigation bar. I cloned it from github and immediately tried to generate a site. This is done by going to the directory and running the following command on the terminal:
$ jekyll serveThis creates a static site that can be accessed from a browser (like Google Chrome) on the URL localhost:4000 . Here is where you see the results. Now, let’s focus on something more important: the directory structure.
** Directory Structure **
Something that is common to all templates is the directory structure. Remember, Jekyll takes in a bunch of HTML, CSS, Markdown and Liquid code (all mixed up and jumbled) and spits out a website by combining various pages. But it relies on a directory structure to do this. In all probablily, the theme you are trying to use contains almost all these files and directories, so let’s see what they are:
-
_config.yml: Perhaps the most important file. This file is where you input the main data. In case of Hyde, this file asks be for my site’s title, baseurl and summary. Any global meta-variables that you need to set for the site go here. So this defines your site’s configuration.
-
_includes/: Let’s look at Hyde to understand this. Hyde has two kinds of sections: sidebar and head (left and right sections respectively). If you visit various pages on the site, you’ll notice that the sidebar does not change at all. Moreover, even in the head column, the formatting is such that the margins from top, left and right remain same. If I wanted to implement this, I’d have to use the same HTML on every page that I create. But that could make the source code (like my post, for instance) look crammed. Liquid offers a solution by using
\{\% include file.html \}The above command pastes the HTML code in file.html instead of it, essentially acting like a placeholder. The _include/ directory, in case of Hyde, store the HTML files with metadata and the formatting for the two sections.
-
_layouts/: In Hyde, there are 3 kinds of pages: default, post, page. Each of them can have a different layout. The type of post is determined from the YAML frontmatter. For instance, notice that each post begins with a title, followed by date followed by summary. Moreover, after each post, there are sections for tags, related posts and comments. This format is fixed by the file _layouts/post.html. This leaves me free to focus only on the content of my post which is injected in between the layout using Liquid’s {{content}} tag. All I need to do, is add a YAML frontmatter and the post will be formatted with the appropriate details! Cool, right?
-
_posts/: This is the directory where all your posts go. Jekyll insists that all your posts be saved in a particular format which is
YEAR-MONTH-DAY-title.MARKUP. Although it seems tedious, it makes extracting dates from posts easy (using Liquid, again!). With Jekyll, once you add the frontmatter, you can write your post in Markdown, without any unnecessary hassles. Remember: Content is King in Jekyll. -
index.html: This is your homepage. There is one important thing that you must note if want to do pagination (breaking post lists into smaller lists). Jekyll’s paginate works on index.html only. So if you want pagination on a page, it must be named index.html, else pagination won’t work. This is why the homepage of this site shows a post list.
-
_site/: This is where Jekyll stores your site content once you run
$jekyll serve. It’s common practice to add this to.gitignoresince you don’t want to be carrying this around.
Before we finish though, there is one important thing that makes Jekyll work: the YAML frontmatter. This appears on top of each page in the site. In case of this post, the frontmatter looks like this:
---
layout: post
comments: true
title: What is Jekyll?
summary: What is Jekyll and how do I get started
tags: jekyll getting-started
---Think of these as attibute:value pairs like in CSS. The frontmatter is processed and used by Liquid. So, layout:post tells Jekyll (via Liquid) to use _layouts/post.html while formatting this page. The other options are default and page. The comments: true tells me that I want to enable Disqus comments for this page. I think title and summary are self explanatory. The tags line allows me to list space separated tags. Through Liquid, this string can be read as an array of tags that I can associate with the post, thus allowing classification by tags. You can add any attribute, give it values (for pages) and interpret it using Liquid in any way you like. Isn’t Liquid awesome?
So now, you have an understanding of what Jekyll does, how do get it installed, where do I find a template and how to interpret the directory structure. With this, you are equipped to begin. Just download the code of a template that you like and play around with it. Take a look at the various HTML, CSS and Markdown files with Liquid code in almost all of them. Soon enough, you’ll know enough to modify the template into the site that you want. In case you need any help from me, do comment below.
All the best.