Web

Jekyll 101

Jekyll is a useful system for templates and blog posts that works for static sites. Here's how you can use it.

Samplasion

Jun 18, 2020 • 3 min read

Jekyll is a useful system for templates and blog posts that works for static sites. You can use this “little” (lol) page to kickstart yourself and, who knows, create the next successful blog. Don’t be scared by the length of this post, you’ll breeze through it.

First of all, create a file named _config.yml. This is a configuration file that, well, uses the YAML syntax. If you’re not familiar with it, I suggest reading this document. Anyway, add a _config.yml file and add a name field. You can give it whatever name you want, just make sure it’s what you want the site to be named. Don’t worry, if you change your mind, you can always come back to it anytime.

You can obviously add other site configuration values. To see a complete list, refer to this document by the Jekyll team.

Obviously, one of the stronger forces of Jekyll is the ability to decrease duplicate code (and consequently typos) by allowing one to create layouts. To create a layout, create a directory _layouts/ next to the config file, and inside, add an index.html file. The contents of this file are what is repeated for each page that uses this layout (more on that later).

A very basic example default layout can be:

<!DOCTYPE html>
<html>
    <head>
        <title>My Blog</title>
    </head>
    <body>
        {{ content }}
    </body>
</html>

Notice the Liquid variable content. That’s the content of the page that uses the layout. A really cool thing you can do is nest layouts. What do I mean? Simple: Maybe you have a template you use for the outer page and a template you use for the content part. You can add a front matter to the content layout with a layout variable that points to the outer page template (default in this fictitious example). That way, you’ll have your content, inside a layout, inside a layout.

But Liquid tags can also have modifiers. For example, you can format a date using {{ page.date | date: "%m/%d/%Y" }}.

To add posts, simply add a _posts directory. To add a post, add a Markdown or HTML file in that directory, then add a front matter. The file should be named in this format: YYYY-MM-DD-title.ext. For example, this post would be named 2020-06-20-jekyll-101.md (assuming a Markdown format, which I use). To use a particular permalink, add a permalink variable to the front matter with the new permalink you want the page or post to be accessible from.

The front matter is the “block” enclosed in --- that sits at the top of every file or so. It can include the title, date of publication, permalink, the layout, or other variables that you can access fron the layouts by using {{CONTEXT.variable}} (where the context is where the front matter is located. For example, a front matter variable in the layout can be accessed with {{layout.variable}}. Likewise, a page/post variable can be accessed using {{page.variable}}). You can also add custom variables that you can access fron the context. For example, you can add a class variable that you can then add to the body from the layout. You can add a front matter to almost everything, to pages, posts and even layouts so you can nest them.

To publish a website to Jekyll and Github Pages, all you need is a _config.yml, a _layouts/default.html layout file and an index.md. You can see a live version here.

For today’s tutorial it’s all, I hope to see you soon. Happy blogging!