11tyThe possum is Eleventy’s mascot

Eleventy Documentation

Menu

Liquid

Template Languages:

Eleventy Short NameFile ExtensionNPM Package
liquid.liquidliquidjs

You can override a .liquid file’s template engine. Read more at Changing a Template’s Rendering Engine.

Liquid Options

Default Options

Rather than constantly fixing outdated documentation, find getLiquidOptions in Liquid.js. These options are different than the default liquidjs options.

Optional: Use your own options New in v0.2.15

It’s recommended to use the Configuration API to set override the default options above.

module.exports = function(eleventyConfig) {
eleventyConfig.setLiquidOptions({
dynamicPartials: true,
strict_filters: true
});
};

Optional: Set your own Library instance New in v0.3.0

As an escape mechanism for advanced usage, pass in your own instance of the Liquid library using the Configuration API. See all liquidjs options.

Not compatible with setLiquidOptions above—this method will override any configuration set there.
module.exports = function(eleventyConfig) {
let liquidJs = require("liquidjs");
let options = {
extname: ".liquid",
dynamicPartials: true,
strict_filters: true,
root: ["_includes"]
};

eleventyConfig.setLibrary("liquid", liquidJs(options));
};

Supported Features

FeatureSyntax
✅ Include{% include user %} looks for _includes/user.liquid. Does not process front matter in the include file.
✅ Includes (Relative Path) New in v0.9.0Relative paths use ./ (template’s directory) or ../ (template’s parent directory): {% include ./included %} looks for included.liquid in the template’s current directory. Does not process front matter.

If _includes/included.liquid also exists, Liquid will use this file instead.
✅ Include (Quoted)
Liquid includes that use quotation marks require dynamicPartials: true—Read more at Quoted Include Paths.
{% include 'user' %} looks for _includes/user.liquid. Does not process front matter in the include file.
✅ Include (Relative Path, Quoted) New in v0.9.0
Liquid includes that use quotation marks require dynamicPartials: true—Read more at Quoted Include Paths.
Relative paths use ./ (template’s directory) or ../ (template’s parent directory): {% include './dir/user' %} looks for ./dir/user.liquid from the template’s current directory. Does not process front matter in the include file.

If _includes/dir/user.liquid also exists, Liquid will use this file instead.
✅ Include (pass in Data){% include 'user' with 'Ava' %}. Does not process front matter in the include file.
✅ Include (pass in Data){% include 'user', user1: 'Ava', user2: 'Bill' %}. Does not process front matter in the include file.
✅ Custom Filters{{ name | upper }} Read more about Filters
Eleventy Universal Filters{% name | filterName %} Read more about Filters
Custom Tags New in v0.5.0{% uppercase name %} Read more about Custom Tags.
Shortcodes New in v0.5.0{% uppercase name %} Read more about Shortcodes.

Quoted Include Paths

This is a common pitfall if you’re using Liquid templates.

If you’d like to use quoted include paths, you must enable dynamicPartials: true in your Liquid options. This default may change in a future major version. Read more about this limitation at Issue #72.

Default behavior, dynamicPartials: false

{% include user %} looks for _includes/user.liquid

Quoted includes with dynamicPartials: true

{% include 'user' %} looks for _includes/user.liquid

Filters

Filters are used to transform or modify content. You can add Liquid specific filters, but you probably want to add a Universal filter instead.

Read more about LiquidJS Filter syntax

module.exports = function(eleventyConfig) {
// Liquid Filter
eleventyConfig.addLiquidFilter("myLiquidFilter", function(myVariable) {});

// Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
eleventyConfig.addFilter("myFilter", function(myVariable) {});
};

Usage

<h1>{{ myVariable | myFilter }}</h1>

Multiple Filter Arguments

module.exports = function(eleventyConfig) {
// Liquid Filter
eleventyConfig.addLiquidFilter("concatThreeStrings", function(arg1, arg2, arg3) {
return arg1 + arg2 + arg3;
});
};
<h1>{{ "first" | concatThreeThings: "second", "third" }}</h1>

Shortcodes

Shortcodes are basically reusable bits of content. You can add Liquid specific shortcodes, but you probably want to add a Universal shortcode instead.

Single Shortcode

module.exports = function(eleventyConfig) {
// Liquid Shortcode
eleventyConfig.addLiquidShortcode("user", function(name, twitterUsername) {});

// Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`
;
});
};

Usage

{% user "Zach Leatherman" "zachleat" %}
Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
</div>

Paired Shortcode

module.exports = function(eleventyConfig) {
// Liquid Shortcode
eleventyConfig.addPairedLiquidShortcode("user", function(bioContent, name, twitterUsername) {});

// Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`
;
});
};

Usage

Note that you can put any Liquid tags or content inside the {% user %} shortcode! Yes, even other shortcodes!

{% user "Zach Leatherman" "zachleat" %}
Zach likes to take long walks on Nebraska beaches.
{% enduser %}
Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>

Related Docs