Liquid

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

Liquid Options Jump to heading #

Default Options Jump to heading #

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 Jump to heading #

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

module.exports = function(eleventyConfig) {
  eleventyConfig.setLiquidOptions({
    dynamicPartials: false,
    strictFilters: false, // renamed from `strict_filters` in Eleventy 1.0
  });
};

Optional: Set your own Library instance Jump to heading #

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

const { Liquid } = require("liquidjs");

module.exports = function(eleventyConfig) {
  let options = {
    extname: ".liquid",
    dynamicPartials: false,
    strictFilters: false, // renamed from `strict_filters` in Eleventy 1.0
    root: ["_includes"]
  };

  eleventyConfig.setLibrary("liquid", new Liquid(options));
};

Supported Features Jump to heading #

Quoted Include Paths Jump to heading #

If you’d like to use include paths without quotation marks, you must enable dynamicPartials: false in your Liquid options. The default in Eleventy 1.0 (and liquidjs) swapped from false to true. Read more about this limitation at Issue #72.

Default behavior, dynamicPartials: true Jump to heading #

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

Non-quoted includes with dynamicPartials: false Jump to heading #

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

Filters Jump to heading #

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 Jump to heading #

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

Multiple Filter Arguments Jump to heading #

module.exports = function(eleventyConfig) {
  // Liquid Filter
  eleventyConfig.addLiquidFilter("concatThreeStrings", function(arg1, arg2, arg3) {
    return arg1 + arg2 + arg3;
  });
};

<h1>{{ "first" | concatThreeThings: "second", "third" }}</h1>

Shortcodes Jump to heading #

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

Shortcode Jump to heading #

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 Jump to heading #

{% 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 Jump to heading #

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 Jump to heading #

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.
{% enduser2 %}

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 Jump to heading #

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 Jump to heading #

(It’s the same.)

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

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

Access to page data values New in v0.11.0 Jump to heading #

If you aren’t using an arrow function, Liquid Shortcodes (and Nunjucks, Handlebars, and 11ty.js JavaScript Functions) will have access to Eleventy page data values without needing to pass them in as arguments.

module.exports = function(eleventyConfig) {
  eleventyConfig.addLiquidShortcode("myShortcode", function() {
    // Available in 0.11.0 and above
    console.log( this.page );

    // For example:
    console.log( this.page.url );
    console.log( this.page.inputPath );
    console.log( this.page.fileSlug );
  });
};

Other pages in Template Languages:

• HTML
• Markdown
• JavaScript
• Nunjucks
• Liquid
• Handlebars
• Mustache
• EJS
• HAML
• Pug
• Custom

Related Docs

• Template Custom Tags
• Template Filters
• Template Shortcodes