Stand with Ukraine 🇺🇦
Eleventy
The possum is Eleventy’s mascot

Eleventy Documentation

WARNING:
This is an older version of Eleventy. Go to the newest Eleventy docs (current path: /docs/shortcodes/) or the full release history.
Menu

IndieWeb Avatar for https://www.11ty.dev/Eleventy runs npm install 89% faster than Remix.

Shortcodes Jump to heading

Contents

Various template engines can be extended with shortcodes for easy reusable content. This is sugar around Template Language Custom Tags. Shortcodes are supported in JavaScript, Liquid, Nunjucks, Handlebars templates.

Here are a few examples:

View this example in: Liquid Nunjucks 11ty.js Handlebars
Filename sample.liquid
{% user firstName, lastName %}

The comma between arguments is optional in Liquid templates.

Filename sample.liquid
{% user firstName lastName %}
Filename sample.njk
{% user firstName, lastName %}

The comma between arguments is required in Nunjucks templates.

Filename sample.11ty.js
module.exports = function({ firstName, lastName }) {
  return `<h1>${this.user(firstName, lastName)}</h1>`;
};
Filename sample.hbs
<!-- Note the three opening and closing curly brackets (the triple-stash) -->
{{{ user firstName lastName }}}
INFO:
Note that if you return HTML in your Handlebars shortcode, you need to use the Handlebars triple-stash syntax (three opening and three closing curly brackets, e.g. {{{ shortcodeName }}}) to avoid double-escaped HTML. If it’s double-escaped a paragraph tag may render as &lt;p&gt;
INFO:
Markdown files are pre-processed as Liquid templates by default. This means that shortcodes available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the shortcodes available for that templating language will also be available in Markdown files.
Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Liquid Shortcode
  eleventyConfig.addLiquidShortcode("user", function(firstName, lastName) { … });

  // Nunjucks Shortcode
  eleventyConfig.addNunjucksShortcode("user", function(firstName, lastName) { … });

  // Handlebars Shortcode
  eleventyConfig.addHandlebarsShortcode("user", function(firstName, lastName) { … });

  // JavaScript Template Function
  eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) { … });

  // Universal Shortcodes are added to:
  // * Liquid
  // * Nunjucks
  // * Handlebars
  // * JavaScript
  eleventyConfig.addShortcode("user", function(firstName, lastName) { … });
};

A shortcode returns content (a JavaScript string or template literal) that is injected into the template. You can use these however you’d like—you could even think of them as reusable components.

Read more about using shortcodes on the individual Template Language documentation pages:

Paired Shortcodes Jump to heading

The shortcodes we saw above were nice, I suppose. But really, they are not all that different from a filter. The real ultimate power of Shortcodes comes when they are paired. Paired Shortcodes have a start and end tag—and allow you to nest other template content inside!

View this example in: Liquid Nunjucks 11ty.js Handlebars
Syntax Liquid
{% user firstName, lastName %}
  Hello {{ someOtherVariable }}.

  Hello {% anotherShortcode %}.
{% enduser %}

The comma between arguments is optional in Liquid templates.

Syntax Nunjucks
{% user firstName, lastName %}
  Hello {{ someOtherVariable }}.

  Hello {% anotherShortcode %}.
{% enduser %}

The comma between arguments is required in Nunjucks.

Syntax Handlebars
{{# user firstName lastName }}
  Hello {{ someOtherVariable }}.

  Hello {{ anotherShortcode }}.
{{/ user }}
module.exports = function(data) {
  let userContent = `Hello ${data.someOtherVariable}

Hello ${this.anotherShortCode()}`;

  return `<h1>${this.user(userContent, data.firstName, data.lastName)}</h1>`;
};

When adding paired shortcodes using the Configuration API, the first argument to your shortcode callback is the nested content.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Liquid Shortcode
  eleventyConfig.addPairedLiquidShortcode("user", function(content, firstName, lastName) { … });

  // Nunjucks Shortcode
  eleventyConfig.addPairedNunjucksShortcode("user", function(content, firstName, lastName) { … });

  // Handlebars Shortcode
  eleventyConfig.addPairedHandlebarsShortcode("user", function(content, firstName, lastName) { … });

  // JavaScript Template Function
  eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) { … });

  // Universal Shortcodes are added to:
  // * Liquid
  // * Nunjucks
  // * Handlebars
  // * JavaScript
  eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) { … });
};

Read more about using paired shortcodes on the individual Template Language documentation pages:

Universal Shortcodes Jump to heading

Universal shortcodes are added in a single place and subsequently available to multiple template engines, simultaneously. This is supported by JavaScript, Nunjucks, Liquid, and Handlebars template types.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Single Universal Shortcode
  eleventyConfig.addShortcode("myShortcode", function(firstName, lastName) { … });

  // Paired Universal Shortcode
  eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) { … });
};

Asynchronous Universal Shortcodes Jump to heading

This is supported by Liquid, Nunjucks, and JavaScript template types (Handlebars is not async-friendly).

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Async support for `addShortcode` and `addPairedShortcode` is new in Eleventy v2.0.0
  eleventyConfig.addShortcode("single", async function(myName) { /* … */ });
  eleventyConfig.addPairedShortcode("paired", async function(content, myName) { /* … */ });

  // Async methods available in Eleventy v0.10.0+
  eleventyConfig.addAsyncShortcode("single", async function(myName) { /* … */ });
  eleventyConfig.addPairedAsyncShortcode("paired", async function(content, myName) { /* … */ });
};

Scoped Data in Shortcodes Jump to heading

A few Eleventy-specific data properties are available to shortcode callbacks.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  // Make sure you’re not using an arrow function here: () => {}
  eleventyConfig.addShortcode("myShortcode", function() {
    // this.page
    // this.eleventy
  });
};

Other pages in Configuration:

Related Docs