Programming Dungeon

Learning Jekyll in a weekend

Learning Jekyll in a weekend

by Alexander Luna 8 min read

I started blogging years ago when I was in highshool. It never became something coninstent and I must have started like a dozen of blogs about my different hobbies. I have exprience using Blogger and Wordpress (paid and free). If I would have known Jekyll existed I would have used it from day one but I didn’t know how to program 3-5 years ago. My point is that Jekyll is a really great blogging tool (my favorite) if you are willing to learn a little.

I knew about Jekyll for about a year now but I never tried doing something with it. This Christmass weekend I worked my way through the docs and learned how incredible Jekyll is.

Why Jekyll is awesome

  1. You get free hosting on github
  2. You have full control of the HTML and CSS (template)
  3. You can add dynamic functionality fairly easy
  4. And you get a nice pool of plugin options (free)

So lets go through everything step by step:

Table of Contents

Installing & Creating a Blog

Before we install Jekyll we need Ruby and already you are presented with different options, for now lets assume you have it installed and if not I highly recommend you use a Ruby Version Manager like rbenv or rvm. Read about both, chose one and install Ruby 2.2 (or higher).

Once you have Ruby installed we can install Jekyll which is just a Ruby Gem: Open Terminal:

gem install jekyll bundler
jekyll new my-blog
bundle exec jekyll serve

Ok, so we installed 2 gems: jekyll and bundler. We already know what Jekyll is. As for Bundler:

Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

It installs gems and does all the dependency management for you which means less time coding (debugging).

Now that we installed, created and even executed our blog, we can take a look at localhost:4000 and you should see your blog running. Now lets quite the server and take a look at everything.

First of all, in Jekyll you are presented with 2 options:

  1. You create everything from scratch (no themes)
  2. You can chose a theme (Jekyll Themes)

At my first run I installed Jekyll and tried building everything from scratch using Bootstrap CDN and design a quick skeleton but I soon noticed that life is easier if you use a theme and customize everything afterward. I went ahead and chose the basically basic theme. We are going to build everything from scratch. The folder/file structure is pretty much the same. Jekyll doesn’t create everything so you have to create the missing files and folders:

.gitignore
404.html
Gemfile
Gemfile.lock
_config.yml
_posts/
_includes/ # partials go here
_layouts/
_sass/
index.md # your entry point

This is how a basic Jekyll project looks like. For the most past each file and folder describes itself. Finally let’s remove the default theme with which our blog comes in _config.yml. For that remove this line:

theme: minima

Layouts & Includes

Currently all our content is served from the index.md file (post layout). We could write all our HTML in here but if we add a new page, we would end up writing the same HTML all over again. Instead Jekyll lets us create layouts inside the layouts/ folder. Layouts are templates that we can create where we add everything that doesn’t change. We can create different layouts and usually you will want to create a default one and then one for every other purpose.

default.html

The default layout has all the HTML that EVERY page is going to need. For example, the HTML tags, header, body, footer. Usually you only want to really change the body which is where you will render your posts, categories, custom content, etc. for example a default.html file could look like this:

<!-- my-blog/_layouts/default.html -->
<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="/assets/stylesheets/main.css">
</head>

<body>
 
 <script async src="/assets/javascripts/main.js"></script>
</body>
</html>

As you can see everything around the content keyword will be served on every page that choses to use this layout. content is a special keyword/variable that Jekyll replaces later with our content. Now that we created our default layout, we can create another layout which is a little more special, called post.html:

---
layout: default
---
<!-- my-blog/_layouts/post.html -->
<main id="main">

 {{ content }}

</main>

All we did was create a new layout which will render our content (blog post). The only difference is that we added front-matter (those dashes ‘-‘ at the top) which is just a small configuration of the layout before it is created. Jekyll always looks at the front-matter and processes it. Inside the front-matter you can specify customization variables and values to your layout. In this case, we are just setting the layout we want to use. That is right, a layout can depend on another layout. This means that our <main> tag and its content will be inserted into our default.html layout. Which gives us flexibility. If we want we can create now an about.html layout with the same logic:

---
layout: default
---
<!-- my-blog/_layouts/about.html -->
<h2>MY ABOUT PAGE</h2>

 {{ content }}

This is all great but when do we render our actual content ? At the root of our project we can create an about.html All we have to add to the file is this:

---
layout: about
---
<!-- my-blog/about.html -->
<h3>
 This will be rendered as content inside the about layout
 and then inside the default layout
</h3>

If we start our server we will that the localhost:4000/about renders All the HTML we wrote in default.html, Jekyll inserted our <h2> tag from the about.html layout and finally it added our <h3> tag from about.html file in our root directory.

Similar to layouts, includes lets us include html partials into our content. We can create a small HTML snippet in our _includes/ folder and insert it anywhere we want. For that lets create a greeting.html file in our _includes/ folder:

<!-- my-blog/_includes/greeting.html -->
<h1>HELLO EVERYONE</h1>

Now we can include that HTML snippet where ever we want using the include tag like this:

---
layout: about
---
<!-- my-blog/about.html -->
<h3>
 This will be rendered as content inside the about layout
 and then inside the default layout
</h3>

  {% include greeting.html %}

If we reload the about page, we can see our <h1> with our greeting appear. And with that we learned how to keep our HTML clean and lean. Both layouts and includes are crucial to make our blogging experience simpler.

Learning Liquid

So far, we have seen these curly braces everywhere and some tags like include and content but where do those come from ? Well it turns out they belong to the Liquid Template Language which lets you execute code and add a certain dynamic to our templates. Thanks to them we can simply tell Jekyll where we want it to render our Post content instead of rewriting all the HTML for every single post. So lets cover the basics.

everything in {{ }} gets outputted
{{ content }}

everything in {% content %} gets evaluated but not outputted
this for example would not render our content
{% content %}

we can create variables like this:
{% assign my_variable = false %}

and we can check conditions using if,
ex: we can show our content if my_variable is true
{% if my_variable %}
 {{ content }}
{% endif %}

we can loop through a list
which we will use a lot
to display each of our posts

{% for product in collection.products %}
 {{ product.title }}
{% endfor %}

For the most part, this is what you will be using the most. For a full list and documentation visit the Liquid GitHub blog. There you can see how you can use filters to manipulate your content and much more.

How to use variables

We have seen how to assign variables in liquid but Jekyll lets us also create site and local variables. Our site variables are defined inside our _config.yml file like this: title: My Blog Title to use these variables we use the liquid curly braces and the site scope like this site.title which will display the blog title. Similar you can add your twitter handle, email, description, many more things.

Apart from those site wide accessible variables Jekyll lets us define local variables for each of our posts which are accessible in our layouts. To assign variables in our post we use the front-matter. For instance we can set a title inside the front-matter the same we set the layout:title: My blog title. We can use them in our post layout like this: page.title. As you can see, we know every post will have a title but our layout can’t know beforehand the title so we declare it inside our post’s front-matter and the layout can use that to dynamically display the post’s title for every post.

Writing Posts

All blog posts in Jekyll have a fixed format. We create them inside your _posts/ folder with this format. We have to use 4 digits for the year, 2 digits for the month and 2 digits for the day separated by a dash each. Generally they are all either markdown files or html files.

YYYY-MM-DD
YEAR-MONTH-DAY-title.md
YEAR-MONTH-DAY-title.html

What are plugins

Plugins like in Wordpress are small add ons that add functionality. In the case of Jekyll you they are more geared towards developers such as sass-converter, coffescript, GitHub gists, etc. My favorite for now is Jekyll admin which lets you add posts and manage your Jekyll blog via a GUI like Wordpress and Blogger.

For a more extensive list, take a look at this repository:

awesome-jekyll-plugins

and the Jekyll Plugins section

How to deploy

Depending on where you plan to deploy you have to a few changes. For this tutorial I assume you want to deploy to Github. In the case of github you have to go to your Gemfile and replace Jekyll with Githubs own version of Jekyll:

gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme"

Then run bundle install again.

For full deployment instructions read Github’s tutorial which is always up to date.

As a final step I encourage you to copy the basically basic theme I mentioned and go through the installation. Try customizing it and apply your new knowledge.

Further Reading: Adding Service Worker to Jekyll