Build Your Own Blog — Jekyll Basics

Published in

thebit

8 min readDec 27, 2018

In my experience, Jekyll can be your worst enemy or your best friend. Once you’ve put in enough time to learn the ins and outs, however, it becomes quite easy and fun to use. While Jekyll is just a static site generator, it’s popularly used to create blogs like this one: https://release.mozilla.org/

Pre-Requisites: You should know some basic HTML & CSS as Jekyll is not its own separate language. Rather, it builds on top of the features that already exist. Also, if you haven’t installed Jekyll yet, take some time to do so using this resource: https://jekyllrb.com/docs/installation/

What is Jekyll?

When you give a baker a request, they’re responsible for turning that request into a reality. How does a baker know how to bake what you’ve requested properly? — a recipe. I like to think of Jekyll in the same sense. You create templates, the recipes, and they’re used however many times as needed. Jekyll is useful here because instead of having to write new code every time you want to publish a new article or post, you can simply make one template that all of your posts will follow the format of. We’ll go over this later, but by the end of this tutorial, you’ll only be worried about writing the posts themselves and not the code.

Get the gist? If you’re looking for a more professional definition of what Jekyll is and how it works, literally, here’s a great resource: http://jekyllbootstrap.com/lessons/jekyll-introduction.html

Templating

The first thing we’ll need to get into is templating — the core of Jekyll itself. Think back to the bakery analogy we went over earlier. I like to think of the templates that exist in Jekyll as cookie cutters of a sort. If you use a gingerbread cookie cutter, then your cookie will come out as a ginger-bread cookie of course. We can apply this same logic to the templates in Jekyll. Once you’ve decided on the look you want for your posts, you’ll be able to mass produce them easily, opposed to having to write code each and every time.

Here’s how:

1. Create Your Initial Layout

Let’s start by creating most all of the files and folders we need beforehand so that we don’t have to worry about them down the line. Create an _layout folder with two files, default.html and post.html inside it. Then, create an _post folder . Finally, create an _config.yml. Your project directory should end up looking something like this:

├── _config.yml
├── _layouts 
│   └── default.html
│   └── post.html
├── _posts

You might be wondering what each of these are and why they matter, here’s an explanation:

_config.yml — We’ll touch more on this later, but for now just know that this file holds the settings for your site. It’s responsible for what your url looks like and more stuff behind the scenes
_layouts — This is where we’ll keep our layouts and templates. It’s named specifically so that Jekyll knows that our templates are in fact in this folder
_posts —This is pretty much the same as the _layouts folder, except it’ll hold our posts
default.html — Template for your index page
post.html — Template for each and every one of your posts

2. Model Your Templates

Building a template is just like building a regular website at first.

I’m going open up the default.html file and go for something simple that displays the title of each post, the date it was created, and a short description, like this:

I used this basic code to do so:

<!DOCTYPE html>
<html><head>
 <title>My Blog</title>
</head><body>
 <div style="text-align: center; border-style: solid; border-color: black; width: 50%;">
  <div>
   <h1>Title</h1>
   <h3>Date</h3>
   <p>Description</p>
   <a href=" "><button>Read</button></a>
  </div>
 </div>
</body>
</html>

Feel free to pause right now and add some css in this file or in another for styling. The CSS won’t affect the functionality of Jekyll.

Now, let’s hop into our post.html file for a second and create our post template. I’m going to display the title, date published, and the content of the article opposed to a description. Here’s what that might look like:

And here’s the code I used (Same elements, less text):

<!DOCTYPE html>
<html>
<head>
 <title>{{ site.title }}</title>
</head>
<body>
 <h1>This is a Post</h1>
 <h3>Published: 4/1/18</h3>
 <p>Text</p>
</body>
</html>

Liquid

Next, we’re going to tie in liquid. If you don’t know already, liquid is a templating language that acts as Jekyll’s toolbox. It’s kind of like a language in itself, given that you have booleans, if and else statements, and so on. Because we’re only covering the basics, I’m not going to go too in depth. However, if you’re interested in everything that liquid has to offer, check out this cool cheat sheet.

Find and Replace

Now, this is where things get interesting. We’re going to start replacing bits and pieces of our code to convert default.html into a template that we can use:

Replace the title of your blog with {{ site.title }}
Replace the title of your article placeholder with {{ post.title }}
Replace the date with {{ post.current-date }}
Replace the description with {{ post.description }}
Give the button a link with a href set to: {{ post.url }}

The product should look something like this:

<!DOCTYPE html>
<html><head>
 <title>{{ site.title }}</title>
</head><body>
 <div style="text-align: center; border-style: solid; border-color: black; width: 50%;">
  <div>
   <h1>{{ post.title }}</h1>
   <h3>{{ post.current-date }}</h3>
   <p>{{ post.description }}</p>
   <a href="{{ post.url }}"><button>Read</button></a>
  </div>
 </div>
</body>
</html>

Noticing a pattern?

We’re going to cover what posts are in a second. But really all that’s happening here is — Jekyll’s asking for the post’s title, date, and description. So when you load up the site later on, it’ll fill in the info based on the post’s elements.

We can also do the same for our post.html template, except this time use “page.” instead of “post.” and replace the the actual writing of the article with {{ content }}. The final product should be this:

<!DOCTYPE html>
<html>
<head>
 <title>{{ site.title }}</title>
</head>
<body>
 <h1>{{ page.title }}</h1>
 <h3>{{ page.current-date }}</h3> <p>{{ content }}</p></body>
</html>

The Posts

Okay great, we’ve got our templates ready for use. Now you may have noticed the strange syntax used in the section. It’s something like {{ post.something }} typically. In this section, we’ll learn about that filling and how it works!

Posts in Jekyll

To create a post, the first thing you’ll have to do is create an .md (markdown) file and place it in your _posts folder. You should name it using this format: yyyy-mm-dd-this-is-a-title.md.
Then inside, add 2x6 dashes like so:

------

Just like in other languages, you can create variables. But, you must include them between the dashes. For example:

---category: blue
author: Candace---

And here’s where things start to connect: One of the variables you must include is the layout variable. It’s used to select which layout you’d like to use. In this case, because we’re creating a post, so we should choose the post template we made earlier

---layout: post---

And then we should add the variables we used in our template:

---layout: post
title:
current-date:
description:---

You can set these variables to whatever you want, except of course layout should always be set to the template you need it to be! Remember that the values of the variables will be used with templates to produce your posts.

Note: There is a built in “date” variable that you can use, kind of like “layout.” I’m not using it here because I’d like to keep things as simple as possible. However, I do suggest taking a look at this link, as it’ll teach you about the various ways it can be formatted and used.

As for the actual writing in the article. All of that should go below the dashes. Ex.

---layout: post
title: Why Pineapple On Pizza Is Disgusting
current-date: 4-1-18
description: It's disgusting, here's why---
To put it plan and simple, you just shouldn't...

Make as many of these as you want, they’ll all show up on your page.

Note: Do not attempt to set dates that are in the future. Jekyll won’t process them, and the post won’t show up

Index Page

The index page has a similar process. Create a file called “index.md” inside of your project folder (not in _layouts or _posts) and set it up with the dashes and all. This time, you don’t need to add any variables besides the title and layout variables. Use the default template.

---
layout: default
title: My Blog
---

Final Touches

The second to last thing we need to do is actually list out our posts, which we can do using a for loop, which will cycle through each post and display them one by one. If you have experience with any other languages, then you may already be familiar with this concept. Whatever you want to be repeated, you must include between {% for post in site.posts %} and {% endfor %}.

<!DOCTYPE html>
<html><head>
 <title>{{ site.title }}</title>
</head><body>
 {% for post in site.posts %}
 <div style="text-align: center; border-style: solid; border-color: black; width: 50%;">
  <div>
   <h1>{{ post.title }}</h1>
   <h3>{{ post.current-date }}</h3>
   <p>{{ post.description }}</p>
   <a href="post.url"><button>Read</button></a>
  </div>
 </div>
 {% endfor %}
</body>
</html>

What’s happening here is that for each post in the folder that is _posts, a div is created along with an encompassing title, date and description.

The final step, which is my favorite, is getting the site up. At this point, pull up your command line and navigate to the directory that contains your project. Then…drum roll…enter jekyll serve. Copy and paste the server address that appears into your browser, refresh, and watch the magic happen. You should get something like this:

And….that concludes it. You learned the basics of Jekyll. Congrats! As I said before, I encourage you to try applying some styling to your templates to truly make this blog your own.

Additional Resources:

What we created in this tutorial only touches the surface of what Jekyll has to offer. It’s possible to add images to your articles, links, whatever it may be. If you’re someone who prefers organization, there’s also a way to categorize your posts using variables. If you’re interested in a more neat homepage and less of an index — it’s even possible to limit the number of posts that appear to only the most recent ones. There’s literally so much you can do. Here a few links to help you down the road: