| eleventyNavigation | relatedKey | relatedTitle | tags | layout | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
liquid |
Template Language—Liquid |
|
layouts/langs.njk |
| Eleventy Short Name | File Extension | NPM Package |
|---|---|---|
liquid |
.liquid |
liquidjs |
You can override a .liquid file’s template engine. Read more at Changing a Template’s Rendering Engine.
Rather than constantly fixing outdated documentation, find getLiquidOptions in Liquid.js. These options are different than the default liquidjs options.
It’s recommended to use the Configuration API to override the default options above.
module.exports = function(eleventyConfig) {
eleventyConfig.setLiquidOptions({
dynamicPartials: true,
strict_filters: true
});
};As an escape mechanism for advanced usage, pass in your own instance of the Liquid library using the Configuration API. See all liquidjs options.
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));
};| Feature | Syntax |
|---|---|
| ✅ Include | {% raw %}{% include user %}{% endraw %} looks for _includes/user.liquid. Does not process front matter in the include file. |
| ✅ Includes (Relative Path) {% addedin "0.9.0" %} | Relative paths use ./ (template’s directory) or ../ (template’s parent directory): {% raw %}{% include ./included %}{% endraw %} looks for included.liquid in the template’s current directory. Does not process front matter.{% callout "warn" %}If _includes/included.liquid also exists, Liquid will use this file instead.{% endcallout %} |
| ✅ Include (Quoted) | {% callout "info" %}Liquid includes that use quotation marks require dynamicPartials: true—Read more at Quoted Include Paths.{% endcallout %}{% raw %}{% include 'user' %}{% endraw %} looks for _includes/user.liquid. Does not process front matter in the include file. |
| ✅ Include (Relative Path, Quoted) {% addedin "0.9.0" %} | {% callout "info" %}Liquid includes that use quotation marks require dynamicPartials: true—Read more at Quoted Include Paths.{% endcallout %}Relative paths use ./ (template’s directory) or ../ (template’s parent directory): {% raw %}{% include './dir/user' %}{% endraw %} looks for ./dir/user.liquid from the template’s current directory. Does not process front matter in the include file.{% callout "warn" %}If _includes/dir/user.liquid also exists, Liquid will use this file instead.{% endcallout %} |
| ✅ Include (pass in Data) | {% raw %}{% include 'user' with 'Ava' %}{% endraw %}. Does not process front matter in the include file. |
| ✅ Include (pass in Data) | {% raw %}{% include 'user', user1: 'Ava', user2: 'Bill' %}{% endraw %}. Does not process front matter in the include file. |
| ✅ Custom Filters | `{% raw %}{{ name |
| ✅ Eleventy Universal Filters | `{% raw %}{% name |
| ✅ Custom Tags {% addedin "0.5.0" %} | {% raw %}{% uppercase name %}{% endraw %} Read more about Custom Tags. |
| ✅ Shortcodes {% addedin "0.5.0" %} | {% raw %}{% uppercase name %}{% endraw %} Read more about Shortcodes. |
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.
{% raw %}{% include user %}{% endraw %} looks for _includes/user.liquid
{% raw %}{% include 'user' %}{% endraw %} looks for _includes/user.liquid
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) { … });
};{% raw %}
<h1>{{ myVariable | myFilter }}</h1>{% endraw %}
module.exports = function(eleventyConfig) {
// Liquid Filter
eleventyConfig.addLiquidFilter("concatThreeStrings", function(arg1, arg2, arg3) {
return arg1 + arg2 + arg3;
});
};{% raw %}
<h1>{{ "first" | concatThreeThings: "second", "third" }}</h1>{% endraw %}
Shortcodes are basically reusable bits of content. You can add Liquid specific shortcodes, but you probably want to add a Universal shortcode instead.
{% codetitle ".eleventy.js" %}
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.
{% raw %}
{% user "Zach Leatherman", "zachleat" %}
<!-- The comma between arguments is optional in Liquid templates -->
{% user "Zach Leatherman" "zachleat" %}{% endraw %}
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
</div>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.
Note that you can put any Liquid tags or content inside the {% raw %}{% user %}{% endraw %} shortcode! Yes, even other shortcodes!
{% raw %}
{% user2 "Zach Leatherman" "zachleat" %}
Zach likes to take long walks on Nebraska beaches.
{% enduser2 %}{% endraw %}
<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>Liquid is already promise-based internally so async functions with await work fine out of the box.
{% codetitle ".eleventy.js" %}
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();
});
};(It’s the same.)
{% raw %}
{% user "Zach Leatherman" "zachleat" %}
{% user2 "Zach Leatherman" "zachleat" %}
Zach likes to take long walks on Nebraska beaches.
{% enduser2 %}{% endraw %}
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 );
});
};