I wanted re-usable ‘components’ on my Jekyll sites which I could use to render common chunks of content. These components would need to accept parameters that would change the layout or styling of the rendered HTML and also accept any HTML that I wanted rendered on the page. After trying a bunch of options I found that Liquid block plugins combined with Nokogiri was the best solution.

Here’s how I wanted it to work

No need to worry about writing markup or classes on my pages, just set a bunch of attributes and params and let the template do the rest:

# Call the component something like this:
<my-custom-component color=red>
	<heading>Big Red Text</heading>
		Any kind of <strong>markup here</strong>.
# Have the markup look something like this:
	<h1 style="color: red">Big Red Text</h1>
		Any kind of <strong>markup here</strong>.

Liquid Blocks + Nokogiri is the answer

The following approach uses a Liquid Tag block type Jekyll plugin letting you pass in any pipeline separated params you might want, and any custom tags into the block. The tags are parsed by Nokogiri allowing for bug free HTML rendering with access to attributes if you need them.

# _plugins/foo/foo.rb
require "jekyll"
require "nokogiri"

module Foo
	class Tag < Liquid::Block
		def initialize(tag_name, input, parse_context)
			@params = parse_params(input.strip)

		def parse_params(input)
			result = {}
			input.split('|').each do | item |
				key = item.split('=').first
				value = item.split('=').last
				result[key] = value.delete_prefix('"').delete_suffix('"')
			return result

		def render(context)
			@text		= super
			elements	= Nokogiri::HTML::DocumentFragment.parse(@text)
			template	= "#{File.dirname(__FILE__)}/template.liquid"
			liquid 		= Liquid::Template.parse(File.read(template))
			variables	= {
				"params" => @params,
				"heading" => elements.search('heading').text,
				"content" => elements.search('content').to_html,

			return liquid.render(variables)
		Liquid::Template.register_tag "foo", self

Your template files can stay nice and neat because all the logic and defaults are handled by Ruby in the plugin.

# _plugins/foo/template.html
<h1 class="{{ params.color }}">
	{{ heading }}
{{ content }}

Call the block like this in your templates:

# page.html
{% foo color=red|size=large %}
	<heading>Big Red Text</heading>
		<p>Any markup here</p>
{% endfoo %}

Using Nokogiri to parse the content has an added benefit of providing access to attributes on any of the tags you pass into the content of a block. Here’s an example of a method I used to render a list of links.

def get_links(elements)
	items = []
		elements.search('links').each do | element |
			items << {
				"label" => element.text,
				"href" => element.attributes['href'].value,
	return items

The links were passed into the block like so:

{% foo %}
	<links href="/">Homepage</links>
	<links href="/about">About us</links>
	<links href="/contact">Contact</links>
{% endfoo %}

Why not just use includes?

Jekyll’s built in includes system was the first approach I tried and it does work but has some drawbacks. Your template would live in _includes and the parameters would be passed in using the standard method:

# _includes/my-custom-component.html
	<h1 style="color: {{ include.color }}">
		{{ include.heading }}
		{{ include.body }}
# page.html
{% include my-custom-component.html
	heading="Big Red Text"
What about passing in HTML?

No problem, we can use the Liquid capture variable to pass in whatever we want:

{% capture body %}
	<p>I'm the body text</p>
{% endcapture %}
Need default parameters?

It’d be useful to have some defaults and we could use Liquid’s ‘default’ method to pull this off. If you only have a few params you can add them inline to your template but I find it’s easier to organise if you have them all listed at the top of the file:

# Inline your defaults if you only have a few
<h1>{% raw%}{{ include.heading | default: "Default Heading" }}</h1>
# List all defaults at the top if you have many
# Note that we renamed the variables here so you'll need to
# use 'heading' instead of 'include.heading' in the template.

{% if include.heading %}
    {% assign heading = include.heading %}
{% else %}
    {% assign heading = "Default Heading" %}
{% endif %}

{% if include.color %}
    {% assign color = include.color %}
{% else %}
    {% assign color = "red" %}
{% endif %}

	<h1>{{ heading }}</h1>
All good so far but here’s where Jekyll includes fall short