11ty

Eleventy Documentation

This documentation is for an older version. Go to the newest Eleventy docs or check out the full release history.

Documentation Pages

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 #

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

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

Optional: Set your own Library instance #

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 ignore any configuration set there.
module.exports = function(eleventyConfig) {
let liquidJs = require("liquidjs");
let options = {
extname: ".liquid",
dynamicPartials: true,
root: ["_includes"]
};
eleventyConfig.setLibrary("liquid", liquidJs(options));
};

Supported Features #

FeatureSyntax
✅ Include{% include user %} looks for _includes/user.liquid
✅ Include{% include 'user' %} looks for _includes/user.liquid (quotes around includes require dynamicPartials: true—read more at #72)
✅ Include (pass in Data){% include 'user' with 'Ava' %}
✅ Include (pass in Data){% include 'user', user1: 'Ava', user2: 'Bill' %}
✅ Custom Filters`{{ name
Eleventy Universal Filters`{% name
Custom Tags{% uppercase name %} Read more about Custom Tags. Added in Eleventy 0.5.0
Shortcodes{% uppercase name %} Read more about Shortcodes. Added in Eleventy 0.5.0

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