- Stable
3.0.0
Toggle Menu
5.81s
40.14s
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:
{% user firstName, lastName %}
The comma between arguments is optional in Liquid templates.
{% user firstName lastName %}
{% user firstName, lastName %}
The comma between arguments is required in Nunjucks templates.
export default function({ firstName, lastName }) {
return `<h1>${this.user(firstName, lastName)}</h1>`;
};
module.exports = function({ firstName, lastName }) {
return `<h1>${this.user(firstName, lastName)}</h1>`;
};
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.
Read more about using shortcodes on the individual Template Language documentation pages:
- JavaScript
*.11ty.js
(async-friendly) - Liquid
*.liquid
(async-friendly) - Nunjucks
*.njk
(async-friendly) - Handlebars
*.hbs
(sync only)
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.
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) { /* … */ });
};
Read more about using paired shortcodes on the individual Template Language documentation pages:
- JavaScript
*.11ty.js
(async-friendly) - Liquid
*.liquid
(async-friendly) - Nunjucks
*.njk
(async-friendly) - Handlebars
*.hbs
(sync only)
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 aboutpage
)this.eleventy
Added in v2.0.0 (Learn abouteleventy
)this.env
(Nunjucks-specific) Added in v3.0.0this.ctx
(Nunjucks-specific) Added in v3.0.0
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.
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
};
Async Friendly Per-Engine Shortcodes
Learn more about these on the individual template engine pages for Nunjucks, Liquid, and 11ty.js
JavaScript.
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:
- Configuration Shapes
- Passthrough File Copy
- Ignore Files
- Filters
- Shortcodes
- Preprocessors
- Custom Tags
- Events
- Transforms
- Watch and Serve
- Memoize