Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
Help Eleventy: Fill out Survey Awesome!
Versions
Stable
3.0.0
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Render

Contents

A plugin to add shortcodes to render an Eleventy template string (or file) inside of another template.

Template Compatibility

This plugin adds a renderTemplate and renderFile asynchronous universal shortcode and a renderContent universal filter to:

  • Nunjucks
  • Liquid
  • JavaScript (11ty.js)

Everything you’ve added to project’s configuration file will also be available in these renders too: shortcodes, filters, etc. That means you can nest 😱 them!

Installation

This plugin is bundled with Eleventy core so it doesn’t require additional installation. But you do have to add it to your configuration file (probably eleventy.config.js) with addPlugin:

eleventy.config.js
import { EleventyRenderPlugin } from "@11ty/eleventy";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(EleventyRenderPlugin);
};
module.exports = async function (eleventyConfig) {
	const { EleventyRenderPlugin } = await import("@11ty/eleventy");

	eleventyConfig.addPlugin(EleventyRenderPlugin);
};
Expand to view all of the Plugin Options
eleventy.config.js
import { EleventyRenderPlugin } from "@11ty/eleventy";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(EleventyRenderPlugin, {
		tagName: "renderTemplate", // Change the renderTemplate shortcode name
		tagNameFile: "renderFile", // Change the renderFile shortcode name
		filterName: "renderContent", // Change the renderContent filter name

		// Only available in Liquid right now
		accessGlobalData: false,   // Does rendered content has access to the data cascade?
	});
};
module.exports = async function (eleventyConfig) {
	const { EleventyRenderPlugin } = await import("@11ty/eleventy");

	eleventyConfig.addPlugin(EleventyRenderPlugin, {
		tagName: "renderTemplate", // Change the renderTemplate shortcode name
		tagNameFile: "renderFile", // Change the renderFile shortcode name
		filterName: "renderContent", // Change the renderContent filter name

		// Only available in Liquid right now
		accessGlobalData: false,   // Does rendered content has access to the data cascade?
	});
};

Usage

renderTemplate Paired Shortcode

Use the renderTemplate paired shortcode to render a template string.

{% renderTemplate "md" %}
# I am a title

* I am a list
* I am a list
{% endrenderTemplate %}
{% renderTemplate "md" %}
# I am a title

* I am a list
* I am a list
{% endrenderTemplate %}
export default async function () {
  return await this.renderTemplate(
    `# I am a title

* I am a list
* I am a list`,
    "md"
  );
};
module.exports = async function () {
  return await this.renderTemplate(
    `# I am a title

* I am a list
* I am a list`,
    "md"
  );
};

The content inside of the shortcode will be rendered using Markdown ("md"). Front matter is not yet supported.

The first argument to renderTemplate can be any valid templateEngineOverride value. You can even use "liquid,md" to preprocess markdown with liquid. You can use custom template types here too.

INFO:
The one exception here is that {% renderTemplate "11ty.js" %} JavaScript string templates are not yet supported—use renderFile below instead.

Pass in data

Both the eleventy and page variables are available inside of these templates by default. If you want to pass in additional data, you can do so like this:

---
myData:
  myKey: myValue
---
{% renderTemplate "liquid", myData %}
{{ myKey }}
{% endrenderTemplate %}
---
myData:
  myKey: myValue
---
{% renderTemplate "liquid", myData %}
{{ myKey }}
{% endrenderTemplate %}
export const data = {
	myData: {
		myKey: "myValue",
	},
};

export async function render(data) {
	return await this.renderTemplate(`{{ myKey }}`, "liquid", data.myData);
};
module.exports.data = {
	myData: {
		myKey: "myValue",
	},
};

module.exports.render = async function (data) {
	return await this.renderTemplate(`{{ myKey }}`, "liquid", data.myData);
};

Outputs myValue.

renderFile Shortcode

Use the renderFile shortcode to render an include file.

{% renderFile "./_includes/blogpost.md" %}
{% renderFile "./_includes/blogpost.md" %}
export default async function () {
  return await this.renderFile("./includes/blogpost.md");
};
module.exports = async function () {
  return await this.renderFile("./includes/blogpost.md");
};

The first argument to renderFile is a project root relative path to any template file. Front matter inside of the target files is not yet supported. The template syntax used is inferred by the file extension.

Note that you can use files supported by any custom file extensions you’ve added too!

Pass in data

Both the eleventy and page variables are available inside of these templates by default. If you want to pass in additional data, you can do so like this:

---
myData:
  myKey: myValue
---
{% renderFile "./_includes/blogpost.md", myData %}
---
myData:
  myKey: myValue
---
{% renderFile "./_includes/blogpost.md", myData %}
export const data = {
  myData: {
    myKey: "myValue",
  },
};
export async function render(data) {
  return await this.renderFile("./includes/blogpost.md", data.myData);
};
module.exports.data = {
  myData: {
    myKey: "myValue",
  },
};
module.exports.render = async function (data) {
  return await this.renderFile("./includes/blogpost.md", data.myData);
};

Override the target file syntax

The syntax is normally inferred using the file extension, but it can be overridden using a third argument. It can be any valid templateEngineOverride value. You can even use "liquid,md" to preprocess markdown with liquid.

---
myData:
  key: value
---
{% renderFile "./_includes/blogpost.md", myData, "njk" %}
---
myData:
  key: value
---
{% renderFile "./_includes/blogpost.md", myData, "njk" %}
export const data = {
  myData: {
    myKey: "myValue",
  },
};
export async function render(data) {
  return await this.renderFile("./includes/blogpost.md", data.myData, "njk");
};
module.exports.data = {
  myData: {
    myKey: "myValue",
  },
};
module.exports.render = async function (data) {
  return await this.renderFile("./includes/blogpost.md", data.myData, "njk");
};

Will render blogpost.md using Nunjucks instead of Markdown!

renderContent Filter

Directly render a string of arbitrary template content.

Consider the following Nunjucks template:

---
myContent: "{{ 'Second' }}"
---
{% renderTemplate %}{{ myContent }}{% endrenderTemplate %} from renderTemplate
{{ myContent | renderContent("njk") }} from renderContent

Outputs:

{{ 'Second' }} from renderTemplate
Second from renderContent

From the Community

+ Add yours!

Other pages in Official Plugins: