jekyll-template

Custom template block with YAML front matter support for Jekyll

Add this line to your application's Gemfile:

gem 'jekyll-template'

And then execute:

bundle

Or install it yourself as:

gem install jekyll-template

Templates ({% template %}) work similarly to Jekyll's {% include %} tag. It references an existing .html file for markup. However, the biggest difference (and most awesome feature) between {% template %} vs. {% include %} is that templates allow for content to be used inside the block.

The first thing you have to do to allow for template blocks to work is to create a new directory called _templates within your Jekyll site's source directory:

my-jekyll-site/
├── _data/
├── _includes/
├── _plugins/
├── _posts/
├── _templates/ <-- Right here!
└── index.md

Once you have your directory created, add template files as regular .html files (just like you would _includes/ files).

Let's create a template file called awesome.html, which will be added to _templates. (Full path is _templates/awesome.html)

<div class="awesome">
  {{ template.content }}
</div>

You can write whatever markup you would like inside a template file. The most important thing is to include a {{ template.content }} tag. This destinates where your content will be rendered.

After creating our awesome.html template, we can use it in any of our Jekyll pages (or posts… heck even in _include files).

For this example, let's add it to our index.md file:

# Hello
{% template awesome.html %}
I am content!
{% endtemplate %}

Your template content needs to begin with {% template %} and end with {% endtemplate %}. Be sure to include the path/name of the template file you wish to use.

The final rendered .html will look like this:

<h1 id="hello">Hello</h1>
<div class="awesome"> <p>I am content!</p> </div>

By default, templates parse and render content as markdown. To force templates to render content as HTML, all the parse: "html" attribute to your {% template %} tag.

{% template awesome.html parse: "html" %}
# Title
I am content! As HTML!
{% endtemplate %}

The final rendered .html will look like this:

<div class="awesome"> # Title I am content! As HTML! </div>

You can add YAML front matter to both your template files, just like Jekyll pages and posts.

---
title: Awesome title
---
<div class="awesome">
  <h1>{{ template.title</h1>

  {{ template.content }}
</div>

Front matter can also be defined in your {% template %} block. Any front matter data defined here will override the data defined in your original template.

{% template awesome.html %}
---
title: Best title
---
I am content!
{% endtemplate %}

<div class="awesome">
  <h1>Best title</h1>
  <p>I am content!</p>
</div>

Yo dawg. I heard you liked templates! The template block supports nesting 👏

{% template outer.html %}
  {% template inner.html %}
    Hi!
  {% endtemplate %}
{% endtemplate %}

More documentation coming soon!

I am not a Ruby developer. (My background is mostly with Javascript). I wrote this plugin based on experimentation and combing through Jekyll's and Liquid's source code + documentation. I'm sure there's probably code in there somewhere that's offensive to Ruby devs.

We've been using {% template %} for many months now on the Help Scout website, and it's been working great! We haven't noticed any slowdowns in build times (and we use a lot of templates).

Many thanks to @alisdair for his help with code review/testing + @hownowstephen for his help with Ruby things.