[go: up one dir, main page]
Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
11ty is joining Font AwesomeIndieWeb Avatar for https://fontawesome.com/
Versions
Stable
3.0.0
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Next.js 70.65s

Shortcodes

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 templates.

Here are a few examples:

sample.liquid
{% user firstName, lastName %}

The comma between arguments is optional in Liquid templates.

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

The comma between arguments is required in Nunjucks templates.

sample.11ty.js
export default function({ firstName, lastName }) {
  return `<h1>${this.user(firstName, lastName)}</h1>`;
};
sample.11ty.cjs
module.exports = function({ firstName, lastName }) {
  return `<h1>${this.user(firstName, lastName)}</h1>`;
};
eleventy.config.js
export default function (eleventyConfig) {
  // Shortcodes added in this way are available in:
  // * Markdown
  // * Liquid
  // * Nunjucks
  // * JavaScript
  // * Handlebars (not async)

  eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });

  // Async-friendly in v2.0.0
  eleventyConfig.addShortcode("user", async function(myName) { /* … */ });

  // Direct async method available
  eleventyConfig.addAsyncShortcode("user", async function(myName) { /* … */ });
};
module.exports = function (eleventyConfig) {
  // Shortcodes added in this way are available in:
  // * Markdown
  // * Liquid
  // * Nunjucks
  // * JavaScript
  // * Handlebars (not async)

  eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });

  // Async-friendly in v2.0.0
  eleventyConfig.addShortcode("user", async function(myName) { /* … */ });

  // Direct async method available
  eleventyConfig.addAsyncShortcode("user", async function(myName) { /* … */ });
};

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

INFO:
Markdown files are pre-processed as Liquid templates by default—any 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.

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!

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

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

The comma between arguments is optional in Liquid templates.

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

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

The comma between arguments is required in Nunjucks.

export default function (data) {
  let userContent = `Hello ${data.someOtherVariable}

Hello ${this.anotherShortCode()}`;

  // pass the content as the first parameter.
  return `<h1>${this.user(userContent, data.firstName, data.lastName)}</h1>`;
};
module.exports = function (data) {
  let userContent = `Hello ${data.someOtherVariable}

Hello ${this.anotherShortCode()}`;

  // pass the content as the first parameter.
  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.

eleventy.config.js
export default function (eleventyConfig) {
  // Shortcodes added in this way are available in:
  // * Markdown
  // * Liquid
  // * Nunjucks
  // * JavaScript
  // * Handlebars (sync only)

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

  // Async support for `addPairedShortcode` is new in Eleventy v2.0.0
  eleventyConfig.addPairedShortcode("user", async function(content, myName) { /* … */ });

  // Async method available
  eleventyConfig.addPairedAsyncShortcode("user", async function(content, myName) { /* … */ });
};
module.exports = function (eleventyConfig) {
  // Shortcodes added in this way are available in:
  // * Markdown
  // * Liquid
  // * Nunjucks
  // * JavaScript
  // * Handlebars (sync only)

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

  // Async support for `addPairedShortcode` is new in Eleventy v2.0.0
  eleventyConfig.addPairedShortcode("user", async function(content, myName) { /* … */ });

  // Async method available
  eleventyConfig.addPairedAsyncShortcode("user", async function(content, myName) { /* … */ });
};
INFO:
Markdown files are pre-processed as Liquid templates by default—any 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.

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

Asynchronous Shortcodes

addShortcode, addPairedShortcode both accept async function callbacks as of Eleventy v2.0.0. addAsyncShortcode and addPairedAsyncShortcode also accept async function callbacks and have been available since Eleventy v0.10.0.

Scoped Data in Shortcodes

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

  • this.page (Learn about page)
  • this.eleventy Added in v2.0.0 (Learn about eleventy)
  • this.env (Nunjucks-specific) Added in v3.0.0
  • this.ctx (Nunjucks-specific) Added in v3.0.0
eleventy.config.js
export default function (eleventyConfig) {
  // Make sure you’re not using an arrow function here: () => {}
  eleventyConfig.addShortcode("myShortcode", function () {
    // this.page
    // this.eleventy
  });
};
module.exports = function (eleventyConfig) {
  // Make sure you’re not using an arrow function here: () => {}
  eleventyConfig.addShortcode("myShortcode", function () {
    // this.page
    // this.eleventy
  });
};

Per-Engine Shortcodes

You can also specify different functionality for shortcodes in each engine, if you’d like. Using the addShortcode or addPairedShortcode function is equivalent to adding the shortcode to every supported template engine.

eleventy.config.js
export default function (eleventyConfig) {
  // Liquid
  eleventyConfig.addLiquidShortcode("user", function(firstName, lastName) {});
  eleventyConfig.addPairedLiquidShortcode("user", function(content, firstName, lastName) {});

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

  // JavaScript Template Function (New in 0.7.0)
  eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) {});
  eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) {}); // Faux-paired shortcode
};
module.exports = function (eleventyConfig) {
  // Liquid
  eleventyConfig.addLiquidShortcode("user", function(firstName, lastName) {});
  eleventyConfig.addPairedLiquidShortcode("user", function(content, firstName, lastName) {});

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

  // JavaScript Template Function (New in 0.7.0)
  eleventyConfig.addJavaScriptFunction("user", function(firstName, lastName) {});
  eleventyConfig.addJavaScriptFunction("user", function(content, firstName, lastName) {}); // Faux-paired shortcode
};
INFO:
Markdown files are pre-processed as Liquid templates by default—any 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.

Async Friendly Per-Engine Shortcodes

Learn more about these on the individual template engine pages for Nunjucks, Liquid, and 11ty.js JavaScript.

eleventy.config.js
export default function (eleventyConfig) {
  // Async-friendly
  // Liquid is already async-friendly
  eleventyConfig.addLiquidShortcode("user", async function() {});
  eleventyConfig.addPairedLiquidShortcode("user", async function(content) {});

  // Nunjucks Async
  eleventyConfig.addNunjucksAsyncShortcode("user", async function() {});
  eleventyConfig.addPairedNunjucksAsyncShortcode("user", async function(content) {});

  // JavaScript Template function
  // (make sure you `await` these when using in templates!)
  eleventyConfig.addJavaScriptFunction("user", async function() {});
  eleventyConfig.addJavaScriptFunction("user", async function(content) {}); // Faux-paired shortcode
};
module.exports = function (eleventyConfig) {
  // Async-friendly
  // Liquid is already async-friendly
  eleventyConfig.addLiquidShortcode("user", async function() {});
  eleventyConfig.addPairedLiquidShortcode("user", async function(content) {});

  // Nunjucks Async
  eleventyConfig.addNunjucksAsyncShortcode("user", async function() {});
  eleventyConfig.addPairedNunjucksAsyncShortcode("user", async function(content) {});

  // JavaScript Template function
  // (make sure you `await` these when using in templates!)
  eleventyConfig.addJavaScriptFunction("user", async function() {});
  eleventyConfig.addJavaScriptFunction("user", async function(content) {}); // Faux-paired shortcode
};

Other pages in Configuration: