Where to learn more about Jekyl

I have been browsing through many Jekyll repos and noticed there are a lot of interesting ways others have setup their Jekyll sites. I’m wondering where the creators of these sites learned it all? I’ve been reading through the Jekyll docs and watching as many YouTube videos that I can find, but it seems like there is so much more that I am missing. Where can I go to learn some of the advanced features of Jekyll?

When I first got started with Jekyll, I had the same issue you did. Most sites, explainers, and training material assume you have some basic understanding of Jekyll, so it is difficult to get your arms around it. The best resource I learned was on the Jekyll website, using the step-by-step tutorial. You can find that here:

Maybe I can help describe things at a very high level. Jekyll is based on the Ruby programming language, which is not too important to know or even care about when you are getting started.

Basically, you create a Jekyll site using Markdown or HTML files. You typically use Markdown for pages where you want to display content, like a blog post. You typically use HTML to design the look-and-feel of a page, like, say, a home page with a navigation bar, logo, and banner ads.

You use CSS, SCSS, or SASS to design the look-and-feel for your site. While not fully set up in a new Jekyll site, you might consider following the pattern that Jekyll sort of starts for you, called the 7-1 pattern. Don’t let that confuse you too much… it is just a simple way to organize your stylesheets. Here is a good article to read. I set up this folder structure for all my new projects, starting with the _sass folder Jekyll provides by default.

Layouts

Jekyll has a powerful feature to ease designing your site and encourages re-use, and that is a _layouts folder (also, there is an _includes folder, but you will get familiar with that as you use layouts).

You can create layouts in HTML that get re-used, so when you have some product pages or a page to display your latest blog, the layout can define exactly how the page should look so you can focus on creating the content for that page. You typically write the content in Markdown. If you are not familiar with that, it is an easy way to write a blog post, for example, without focusing on HTML. Let’s say you are writing a blog post. This is what the content you write might look like:

## Here is my big idea
What I want to do is share something important with you, and it is as follows:
1. Do this
2. Do that
3. Do another thing

Jekyll will convert that markdown to standard HTML that any browser can display, like this:

<h2>Here is my big idea</h2>
<p>What I want to do is share something important with you, and it is as follows:</p>

<ol type="1">
    <li>1. Do this</li>
    <li>2. Do that</li>
    <li>3. Do another thing</li>
</ol>

The browser will display the code like this:


Here is my big idea

What I want to do is share something important with you, and it is as follows:

  1. Do this
  2. Do that
  3. Do another thing

Here is a great resource for getting started with markdown:

By using a layout, you can add all the other parts of your site, like the logo, navigation bar, footer, and anything else. You can use stylesheets to change the font colors and look-and-feel of your site.

Blog aware

Jekyll is blog-aware, meaning that it has two folders that will either already be there when you create a site, or you will create them by hand. The first is called _drafts, and the second is called _posts. Drafts are where you create blog items that are still a work in progress. Posts are where your final blog posts exist, and they will display on the website. You can use a date field to say “do not publish until this date,” which is nice, so I typically forgo using the drafts folder altogether.

Static site

Jekyll does not run on a database. It is one in a crowded field of so-called Jamstack site generators (Jam = Javascript Apis and Markup). Don’t let the acronyms confuse you. The idea is that database-driven websites like WordPress and Drupal (and .net, and PHP, and so on) are great, but add levels of complexity, are harder to test, and tend to be slower. An html file with some graphics linked to them in a folder will always display faster than an HTML file built on-the-fly from a database. People say static sites are also more search-engine friendly, so I can believe that but have no evidence to back it up.

Let’s say you create a beautiful Jekyll site. You use Markdown, which browsers do not understand (they understand HTML), you use SASS or SCSS, which browsers do not understand (they understand CSS), you use layouts and include files that browsers do not understand. So how the heck does Jekyll work?

You build the site. Anytime you design the site, Jekyll will take all the code you wrote and compile it into a so-called static site. That site lives in the _site folder of your Jekyll folder (or repo). So the code you write at the root folder/subfolders all gets generated into pure html and css in the _site folder, and that is essentially where your website is located.

YAML (YML)

When you build a Jekyll site, you will want to use more than html, Markdown, and CSS. For example, let’s say you want to create your own web page that lists all your blog posts. You also want to display the author for the post and maybe even have some special fields you want to display (like categorization or tag). Jekyll has some of those fields built-in, but you might create your own, too, like, say, a featured image.

To do both those things, Jekyll uses two technologies. One is YAML, which you will hear referred to as YAML front matter (or YML front matter). If you are not familiar with YAML, it is simply a way to represent data. For example, if you have ever used JSON, comma-separated variables (CSV), or some other format to collect and view data, YML is just another straightforward way of defining data.

You will see lots of files in Jekyll with YML front matter, which you include at the very top of your html or markdown file with two sets of three dashes, like this: ---.

For example, a web page might look like this:

---
layout: default
--- 
Welcome to my website!

When Jekyll reads that file and builds it to your _site folder, it will first display the layout you created for that page (more on that in a minute), and then it will display the content for your page.

A blog might look like this:

---
title: A day in the life of a programmer
date: 2020-02-01
layout: blogpage
---

If you want, you can add pretty much any front matter you need. For example, out of the box, Jekyll does not have the concept of a featured image for a blog, but maybe you want to add one, so you do that like this:

---
title: A day in the life of a programmer
date: 2020-09-01
layout: blogpage
featured-image: /assets/featured-images/coder.png
---

If you are used to more advanced sites, you might be thinking, “wait, where do I register this new featured-image item?”. That is not necessary. You add it to the YAML front matter, and it is registered for that page or any other pages that use it! YAML supports arrays, dates, and other data types, so you can read up on that on the Jekyll site tutorial I sent you.

Coding with Liquid

Now you might be asking me, “so that is cool. I can create a variable called featured-image, so how do I use it?” or you might be asking, “what if I want to create a custom page that lists all my blog posts?”

The answer here is a rudimentary but very powerful programming language created by the folks at Shopify and adopted (mostly) by Jekyll. That language is called Liquid, and there is a great reference for that with pretty much all the info you need at this site (no need to download Liquid because it comes built-in with Jekyll):

Let’s use that featured image approach again.

Here, you have a blog post in your _posts folder, and it has a particular filename of 2021-02-01-a-day-in-the-life-of-a-coder.md (yyyy-mm-dd-title-of-post-separated-by-dashes.md, where md stands for markdown). Once again, we have the blog post that looks like this:

---
title: A day in the life of a programmer
date: 2020-09-01
layout: blogpage
featured-image: /assets/featured-images/coder.png
---
Allow me to explain what a typical day looks like...

In our _layouts folder, we have a file called blogpage.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    {%- assign fi = post.featured-image |relative_url -%}
    <img src="{{- fi -}}" alt="">
    <h2>Title of blog post: {{post.title}}</h2>
    <strong>Date of blog post: {{post.date}}</strong>
    {{content}}
</body>
</html>

That is a standard HTML file, but in my case, I use some Liquid code in the <body> area (note: you can use Liquid anywhere you want, not just the body).

Notice how I display variables using double brackets like this: {{ variable }} and I write logic using bracket percentage like this: {% my code %}. A little quirk with writing the code is sometimes your code will add inadvertent space to your html so that you can remove that extra space with a - like this: {{- variable -}} or {%- my code -%}.

the output might look something like this:


Title of blog post: A day in the life of a programmer

Date of blog post: 2020-09-01
Allow me to explain what a typical day looks like…


Now, let’s take that a step further and say you want to use Liquid to create your very own blog page listing, and you want it to be on the home page of your site. You can create a root file like this:

/index.html (or index.md or index.markdown)

---
layout: bloglist
---

Technically, you could open up the index file and manually add links for every single post when you write, but why not automate it? Since the layout is called bloglist (something you made up), create that file in the _layouts folder and add some html.

/_layouts/bloglist.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <h2>My blog posts</h2>
    {%- assign posts = site.posts -%}
    {%- for post in posts -%}
        {%- assign post-url = post.url | relative_url -%}
        Titlle: <a href="{{post-url}}"></a> Title: {{post.title}}
    {%- endfor -%}
</body>
</html>

The result will be a page that looks something like this:


My blog posts

Title: A day in the life of a programmer
Title: How I got my first programming job


Work in a “There is no Jekyll” mindset

I said there is no server back-end for all this, so how do you take all that code and turn it into a web page? This is where It is time to stop thinking about your site as a “Jekyll site”, but any other website you build with HTML standards. It just so happens that Jekyll generates the site for you.

If you are debugging on your desktop, you will use a command like this: bundle exec jekyll serve or my favorite: bundle exec jekyll serve --livereload, so you can see all the changes you make in real-time on your browser.

If you are using GitHub with GitHub Pages, it will automatically build your site any time you make a change. It will also re-build your site to accommodate future-dated posts.

I find it much easier to think like this: “okay, I am coding a site with some cool tools like Markdown, SCSS, and Liquid to make my life easier, but the output is anything I can imagine in HTML.”

Designing something cool

All this brings me back to your original question: You can create a Jekyll site to look the way you want because it is just a generator, not a design tool.

Now that your mind is freed from “I am building a Jekyll site” to “I am building an HTML website,” all you really need to do is get really good at HTML and CSS (or SASS or SCSS), and Liquid. If your site is really complex, learning JavaScript is useful, but I personally never use it.

For example, I hired a person on Fiverr (https://www.fiverr.com) to create a website for me in Photoshop format. I then took the requirements and wrote the HTML and SCSS, so it looks like the design. Jekyll does not really hamper me so long as I write industry-standard code that I know a browser can display or use the stack Jekyll provides me.

Jekyll comes with a built-in theme called minima, which you will get if you run the jekyll new mysite command. If you do not want to use a theme and get the base scaffolding for a site, you type jekyll new mysite --blank.

Themes and plugins

Of course, a vibrant community of developers builds themes, and most are available for free. However, I would stress that those themes are only as good as the programmer who creates them. Some strictly follow the Jekyll structure I share with you in this article, and others are cobbled together with string and chicken wire. Note that these themes will use whatever technology the developer wants to use. For example, I built my site 100% responsive using CSS Grids, SASS Mixins, and HTML. Other developers will rely heavily on JavaScript, outside JavaScript libraries, or Google fonts, etc. So know what you are getting into. Sometimes customizing a theme is harder than creating a site from scratch, so be warned.

Plugins can also be useful. For example, many common ones help you with search engine optimization or to improve how something gets displayed on your site. That is where the Ruby programming language starts to come in. I often find that the plugins are useful, but be warned that they also only have the features the programmer wants to provide, so if you feel like customizing it, know that you might need a new skillset.

Personally, I am removing most plugins from my site and using my own Liquid code so I have more control. I also do not want to learn Ruby :slight_smile:

Learning Jekyll and GitHub Pages YouTube Playlist

I hope sharing this knowledge helps you get started. Here is a playlist I occasionally update with videos that show you how to use Jekyll, such as creating your own blog feed.

Start of the GitHub and Jekyll Playlist:

If you want to jump right in and see how you can create something different and unique on your website without using a theme or out-of-box Jekyll code, check out this 3-part video series:

One Jekyll feed to rule them all



I hope this helps!

4 Likes

This sort of guide is something I’ve been needing myself! Thank you so much!!

2 Likes

You are very welcome!

1 Like

Very helpful. Thank you Bill.

2 Likes

This is so true. Different people often come up with different solutions to the same issues, so when using a theme it’s hard to know why things are were they are and what you can change without breaking anything else.

Regarding learning to use Jekyll

I’d suggest learning what you need as you go, when you need it. Start making the website you want with plain HTML (and CSS too if you want), then when you reach a part where you need Jekyll to do something, Google how to do it.

For example, say you’re making a blog page. Start with a header section, then make one blog post thumbnail card and then you’ll think “ok, I need this card to repeat for each blog post. Let’s Google how to do that with Jekyll!”

If you only learn out of context, you’ll forget everything pretty quickly, or rather, you’ll never truly learn it in the first place.

1 Like