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

Shortcodes #

Added in Eleventy 0.5.0

Various template engines can be extended with shortcodes for easy reusable content. This is sugar around Template Language Custom Tags. Here’s an example:

<!-- Liquid -->
{% user firstName lastName %}
<!-- Nunjucks, commas between arguments -->
{% user firstName, lastName %}
<!-- Handlebars -->
{{ user firstName lastName }}

Supported in Liquid, Nunjucks, Handlebars templates.

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) { … });
  
  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
  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 #

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!

<!-- Nunjucks, commas between arguments -->
{% user firstName, lastName %}
  Hello {{ someOtherVariable }}.
  
  Hello {% anotherShortcode %}.
{% enduser %}
<!-- Liquid -->
{% user firstName lastName %}
  Hello {{ someOtherVariable }}.
  
  Hello {% anotherShortcode %}.
{% enduser %}
<!-- Handlebars -->
{{# user firstName lastName }}
  Hello {{ someOtherVariable }}.
  
  Hello {{ anotherShortcode }}.
{{/ user }}

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

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) { … });
  
  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
  eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) { … });
};

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

Universal Shortcodes #

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

module.exports = function(eleventyConfig) {
  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
  
  // Single Universal Shortcode
  eleventyConfig.addShortcode("myShortcode", function(firstName, lastName) { … });
  
  // Paired Universal Shortcode
  eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) { … });
};

Related Docs