Simple Web Templating with Jekyll

3 min readMay 16, 2020

Jekyll is a well-supported static site generator that makes it easy to build websites using templates and themes, without having to duplicate HTML or add JS code to your frontend. In this tutorial, we’ll walk through some basic use cases of Jekyll’s templating system from scratch.

Prerequisites

Knowledge of HTML and command line is important for comprehension, but don’t worry if you don’t know Ruby, as most Jekyll sites don’t require custom Ruby code.

Installing Jekyll

Jekyll can be installed using gem, the package manager for the Ruby programming language. A version of Ruby comes preinstalled on macOS Catalina and earlier, but if you’re on a different system you may need to download Ruby manually.

gem install jekyll

Creating a layout

While Jekyll has a default template (used via jekyll new ),we don’t need most of the features it offers, and it’s easier to understand how templating works by starting from scratch. You may want to create a directory first to keep your Jekyll site separate from other projects.

One common issue with writing static HTML sites by hand is the repetition in copying <head> tags, navbars, footers, scripts, and other common HTML between pages. Jekyll’s most basic form of templating is a layout file, which stores common HTML structures of related pages and inserts custom content inside each instance. All layouts go in the _layouts directory, any any page can use them.

Let’s create our main HTML template in _layouts/default.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8">
    <title>My Jekyll Site</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

{{ content }} is how we use the layout’s content variable, which contains the actual HTML content of each page as it’s built.

Creating pages

By default, Jekyll pages can be placed in the root of the site (or subdirectories) and can use HTML or Markdown content.

Let’s start with our default page, index.html, in our site’s root directory. This functions similarly to how a plain index file would without Jekyll, except it’s used within our default.html layout’s content variable. To tell Jekyll to use the default layout, we use default: layout in the file’s YAML metadata section (which is always in between two sets of ---).

---
layout: default
---<h1>My Jekyll Site</h1>
<p>Hello, world!</p>

Alternatively, we can write the same content in index.md using Markdown to make content easier to read and write, without having to rely on an external content editor. Either way, any custom HTML is fully supported!

---
layout: default
---# My Jekyll Site
Hello, world!

Running Jekyll

Now to see the result of our work, we’ll need to run jekyll serve to start a local Jekyll server. By default, Jekyll will build and serve your site at http://localhost:4000/, rebuilding after content changes.

Production note

While jekyll serve is convenient for development, it’s not an ideal server for production. Instead, jekyll build should be used to build Jekyll sites to static HTML files in _site. These static files don’t rely on a backend, so they should work with any existing static file server. Alternatively, you may find it easier to deploy your site with a static site host like GitHub Pages (free for open source GitHub repositories) or Netlify (free for most sites and very flexible). For more in depth instructions and recommendations, check out the official deployment guide.

Creating includes

Reusing common template code between HTML files is useful, but sometimes we need to share common HTML within a page’s content. For that, we can put shared content in the _includes directory, which can then be referenced inside pages, layouts, or even other includes.

The basic code for using an include is {% include example.html %} . Similarly to the content variable in a layout, this will grab the contents of the referenced file, which in this case would be located at _includes/example.html . You can create as many as you like as long as the filename matches a file in _includes.

Next steps

We’ve covered the basics of what makes Jekyll useful for HTML sites written from scratch, but it can also help with more complex use cases. For example, if you want to create multiple pages and blog posts quickly, you can follow the quickstart guide to use the default theme, which sets up layouts, styles, and blogging features automatically. For a more in-depth overview of Jekyll’s most useful features, try out the step by step tutorial, which covers custom metadata fields, data files, blogs, and deployment.