jekyll: static websites with mustaches

This is the first post for opensource.com in a series on Jekyll, a static website generator.

In this post, I’ll start you down the road to building sites with Jekyll, a set of tools and modules that leverage templates, variables, and data in powerful ways for the construction of static websites.

In the next post, I’ll tell you a bit of a story about why I like using Jekyll. However, I know you want to dive in, and don’t want to listen to me telling stories. But, my time will come…

installation

First, you need to install Jekyll. I can’t help you here. You can follow Jekyll’s documentation for your operating system. If you do a YouTube search for “jekyll install,” you’ll find a bazillion videos that will walk you through this.

Go ahead. I’ll wait.

getting started

No one I know “just builds a website.” I mean, no one wakes up in the morning and says “I NEED TO BUILD A WEBSITE.” We can argue the details, but I will be right. Now, that said, roughly 73% of the world’s population wakes up every day and says I wish I could build a website about late 1990’s cat memes. I have talked to people from all over this crazy world, and that is one fundamental constant… even for college students born in the year 2000. Late 90’s cat memes. They’re a thing.

I’ll use asciinema throughout this post series to demonstrate things. Here, I’m going to write the landing page for my new cat memes website. I’m going to write it in Markdown. If you’re not familiar with Markdown, this is a good time. Juan Islas wrote an opensource.com article on it back in September of 2019, so you might go check that out. Come back when you’re ready.

You’ll also see that there is some “frontmatter.” This is actually some YAML at the front, which lets me define variables. The only variable I’m defining is a page title. More on that in a moment.

In this terminalcast, you’ll see I ran into an error. The problem was I was running Jekyll in another terminal so that I could preview this post. So, now you’ve seen what happens if you run Jekyll twice… by running jekyll s (or jekyll serve), you are running a webserver on your local machine that only you can see. But, you can’t run two at the same time… which I tried to do. I went off, and behind the emerald curtain, I stopped the one for this post, and started the one for my new cat meme site.

The resulting website is, as you can see, amazing.

a minimal website

markdown

I like working with Jekyll because it will render my Markdown to HTML. I would rather not write HTML if I can avoid it, especially when I want to focus on content. My first page is a Markdown file with almost no Markdown in it, but as the site grows, I’ll take more advantage of this markup language. Markdown language? Anyway… moving on…

templates

The content for this site is going to come later; I am going to want to drive this site with data, and that’s not part of step one. Before I get there, I’m going to focus on creating a common look for the site, and making sure that every page will consistently render as validating HTML. This involves one of my favorite features of Jekyll: templates.

Right now, I have a single page. While it is… minimalist, it could use a touch of styling. In fact, it could actually use something to make it valid HTML. Right now, Jekyll takes my page (index.md) and turns it into index.html, which contains the following:

<p>The beginnings of a legend. Or… legends revisited.</p>

<p>Insert content here.</p>

This is HTML, but not valid HTML. We can’t have that. At the least, there needs to be an html tag, and a head tag, and a body tag… a whole bunch of stuff.

I’m going to create a new directory called _layouts. In that folder, I’ll place a file called default.html. Watch some terminal TV:

Here, I’ve created a valid HTML5 “template.” This is the shell that will be wrapped around the pages that I write. Now, if I build the site (either by saying jekyll build, or if I want to view the site live, jekyll serve), the contents of index.html will look like this:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title> 90's Cat Memes </title>
  </head>
  <body>
    <p>The beginnings of a legend. Or… legends revisited.</p>

    <p>Insert content here.</p>
  </body>
</html>

Oooh.

What happened?

Jekyll took my content, which was in index.md:

---
title: 90's Cat Memes
layout: default
---

The beginnings of a legend. Or... legends revisited. 

Insert content here.

Jekyll “pushed” this content through the template, _layouts/default.html:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title> {{ page.title }} </title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

Jekyll looked for template variables. These are indicated via the mustaches, or double-curly-brackets (e.g. {{ and }}). The first variable Jekyll encountered was called page.title. This variable will look at the frontmatter on a Markdown file (which is YAML), and try and find a title variable. In the case of my index page, title “90’s Cat Memes”. Then, Jekyll finds the variable content, which is set to the body of the page it is processing.

When Jekyll is done, it emits index.html in the _site directory. This file is the combination of the template and the content. The contents of the final index.html look like this:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title> 90's Cat Memes </title>
  </head>
  <body>
    <p>The beginnings of a legend. Or… legends revisited.</p>

    <p>Insert content here.</p>
  </body>
</html>

The resulting site is no more impressive than it was before (I mean, it was amazing to begin with, so the bar is already set high), but is now a valid HTML5 webpage. And, for every new page I write in Markdown, I can reuse that template, and be guaranteed a validating results.

more variables, data, hosting

There’s a lot more to Jekyll. This was step one. I’m not going to cover everything in the first post, but you’re on your way. In the next post, I’ll spend more time with variables and the organization of your site data in Jekyll. And, I’ll start pointing to resources online that can carry you further.

get the code

This code is avaialble on Github in the repository opensourcecom-catmemes. The code that was written for this post can be referenced via commit 8ff8202. That is, if you browse or clone this URL, you will get the code as it existed when this post was written. The code is licensed CC0, so you can use it any way you want.


This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.