Templates in Jekyll

Templates are used to contain a page’s or post’s content. All templates have access to a global site object variable: site as well as a page object variable: page. The site variable holds all accessible content and metadata relative to the site. The page variable holds accessible data for the given page or post being rendered at that point.

Create a Template

Templates are created by properly formatting a file and placing it in the _layouts directory.


Templates should be coded in HTML and contain YAML Front Matter. All templates can contain Liquid code to work with your site’s data.

Rending Page/Post Content in a Template

There is a special variable in all templates named : content. The content variable holds the page/post content including any sub-template content previously defined. Render the content variable wherever you want your main content to be injected into your template:

  <div id="sidebar"> ... </div>
  <div id="main">


Sub-templates are exactly templates with the only difference being they define another “root” layout/template within their YAML Front Matter. This essentially means a template will render inside of another template.


In Jekyll you can define include files by placing them in the _includes folder. Includes are NOT templates, rather they are just code snippets that get included into templates. In this way, you can treat the code inside includes as if it was native to the parent template.

Any valid template code may be used in includes

#####Using Liquid for Templating

Templating is perhaps the most confusing and frustrating part of Jekyll. This is mainly due to the fact that Jekyll templates must use the Liquid Templating Language.

What is Liquid?

Liquid is a secure templating language developed by Shopify. Liquid is designed for end-users to be able to execute logic within template files without imposing any security risk on the hosting server.

Jekyll uses Liquid to generate the post content within the final page layout structure and as the primary interface for working with your site and post/page data.

Why Do We Have to Use Liquid?

GitHub uses Jekyll to power GitHub Pages. GitHub cannot afford to run arbitrary code on their servers so they lock developers down via Liquid. Liquid is Not Programmer-Friendly.

The short story is liquid is not real code and its not intended to execute real code. The point being you can’t do jackshit in liquid that hasn’t been allowed explicitly by the implementation. What’s more you can only access data-structures that have been explicitly passed to the template.

In Jekyll’s case it is not possible to alter what is passed to Liquid without hacking the gem or running custom plugins. Both of which cannot be supported by GitHub Pages.

As a programmer - this is very frustrating.

But rather than look a gift horse in the mouth we are going to suck it up and view it as an opportunity to work around limitations and adopt client-side solutions when possible.

#####Static Assets

Static assets are any file in the root or non-underscored subfolders that are not pages. That is they have no valid YAML Front Matter and are thus not treated as Jekyll Pages. Static assets should be used for images, css, and javascript files.

#####How Jekyll Parses Files

Remember Jekyll is a processing engine. There are two main types of parsing in Jekyll.

  • Content parsing.
    This is done with textile or markdown.

  • Template parsing.
    This is done with the liquid templating language.

And thus there are two main types of file formats needed for this parsing.

  • Post and Page files.
    All content in Jekyll is either a post or a page so valid posts and pages are parsed with markdown or textile.

  • Template files.
    These files go in _layouts folder and contain your blogs templates. They should be made in HTML with the help of Liquid syntax. Since include files are simply injected into templates they are essentially parsed as if they were native to the template.

Arbitrary files and folders.

Files that are not valid pages are treated as static content and pass through Jekyll untouched and reside on your blog in the exact structure and format they originally existed in.

Formatting Files for Parsing.

We’ve outlined the need for valid formatting using YAML Front Matter. Templates, posts, and pages all need to provide valid YAML Front Matter even if the Matter is empty. This is the only way Jekyll knows you want the file processed.

YAML Front Matter must be prepended to the top of template/post/page files:

 layout: post
 category : pages
 tags : [how-to, jekyll]
 ... contents ...

Three hyphens on a new line start the Front-Matter block and three hyphens on a new line end the block. The data inside the block must be valid YAML.

Defining Layouts for Posts and Templates Parsing.

The layout parameter in the YAML Front Matter defines the template file for which the given post or template should be injected into. If a template file specifies a layout parameter, it is effectively being used as a sub-template. That is to say loading a post file into a template file that refers to another template file will work in the way you’d expect; as a nested sub-template.

#####How Jekyll Generates the Final Static Files.

Ultimately, Jekyll’s job is to generate a static representation of your website. The following is an outline of how that’s done:

  1. Jekyll collects data.
    Jekyll scans the posts directory and collects all posts files as post objects. It then scans the layout assets and collects those and finally scans other directories in search of pages.

  2. Jekyll computes data.
    Jekyll takes these objects, computes metadata (permalinks, tags, categories, titles, dates) from them and constructs one big site object that holds all the posts, pages, layouts, and respective metadata. At this stage your site is one big computed ruby object.

  3. Jekyll liquifies posts and templates.
    Next jekyll loops through each post file and converts (through markdown or textile) and liquifies the post inside of its respective layout(s). Once the post is parsed and liquified inside the the proper layout structure, the layout itself is “liquified”. Liquification is defined as follows: Jekyll initiates a Liquid template, and passes a simpler hash representation of the ruby site object as well as a simpler hash representation of the ruby post object. These simplified data structures are what you have access to in the templates.

  4. Jekyll generates output.
    Finally the liquid templates are “rendered”, thereby processing any liquid syntax provided in the templates and saving the final, static representation of the file.

Notes. Because Jekyll computes the entire site in one fell swoop, each template is given access to a global site hash that contains useful data. It is this data that you’ll iterate through and format using the Liquid tags and filters in order to render it onto a given page.

Remember, in Jekyll you are an end-user. Your API has only two components:

  1. The manner in which you setup your directory.
  2. The liquid syntax and variables passed into the liquid templates.

All the data objects available to you in the templates via Liquid are outlined in the API Section of Jekyll-Bootstrap. You can also read the original documentation here: http://jekyllrb.com/docs/variables/