Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
Eleventy, 2024 in Review
Versions
Stable
3.0.0
Canary
3.0.1-alpha.4
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Next.js 70.65s

Shortcodes

Contents

各种模板引擎都支持通过快捷码（shortcodes）实现内容重用。快捷码（shortcodes）是模板语言（Template Language）基于 自定义标签（Custom Tags） 提供的一种语法糖。JavaScript、Liquid、Nunjucks 模板语言均支持 快捷码（Shortcodes）。

以下是几个示例：

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.

请阅读各个模板语言关于快捷码（shortcodes）的文档以了解更多信息：

配对快捷码（Paired Shortcodes）

从上面所了解到的快捷码（shortcodes）信息来看，它还是挺不错的。但实际上，快捷码和过滤器（filter）没有什么不同。其实，当快捷码（Shortcodes）配对使用时才能体现出它的强大之处。配对快捷码（Paired Shortcodes）由一个开始标签和一个结束标签组成，并且允许你在其中嵌套其它模板内容！

{% 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:

相关文档