Liquid

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.

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 #

Quoted Include Paths #

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.

Shortcode #

module.exports = function(eleventyConfig) {
  // Liquid Shortcode
  // These can be async functions too
  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>`;
  });
};

liquidjs is already Promise-based internally, so an async function for a shortcode function works out of the box here.

Usage #

{% user "Zach Leatherman", "zachleat" %}

<!-- The comma between arguments is optional in Liquid templates -->
{% 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
  // These can be async functions too
  eleventyConfig.addPairedLiquidShortcode("user2", function(bioContent, name, twitterUsername) { … });
  
  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
  eleventyConfig.addPairedShortcode("user2", 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>`;
  });
};

liquidjs is already Promise-based internally, so an async function for a shortcode function works out of the box here.

Usage #

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

{% user2 "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>

Asynchronous Shortcodes #

Liquid is already promise-based internally so async functions with await work fine out of the box.

module.exports = function(eleventyConfig) {
  eleventyConfig.addLiquidShortcode("user", async function(name, twitterUsername) {
    return await fetchAThing();
  });

  eleventyConfig.addPairedShortcode("user2", async function(content, name, twitterUsername) {
    return await fetchAThing();
  });
};

Usage #

(It’s the same.)

{% user "Zach Leatherman" "zachleat" %}

{% user2 "Zach Leatherman" "zachleat" %}
  Zach likes to take long walks on Nebraska beaches.
{% enduser2 %}

Other pages in Template Languages:

• HTML
• Markdown
• JavaScript
  • JavaScript Template Literals
• Nunjucks
• Liquid
• Handlebars
• Mustache
• EJS
• HAML
• Pug

Related Docs

• Template Custom Tags
• Template Filters
• Template Shortcodes