Docs for 11ty/eleventy#3370

11ty · Sep 27, 2024 · 234abc3 · 234abc3
1 parent 666d830
commit 234abc3
Show file tree

Hide file tree

Showing 9 changed files with 114 additions and 91 deletions.
diff --git a/src/_includes/snippets/plugins/rendercontent.njk b/src/_includes/snippets/plugins/rendercontent.njk
@@ -0,0 +1,71 @@
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs persist sync class="tabs-flush">
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendercontent"} %}
+  <div id="rendercontent-liquid" role="tabpanel">
+
+{% raw %}
+
+```liquid
+---
+myData:
+  key: value
+---
+{% renderFile "./_includes/blogpost.md", myData, "njk" %}
+```
+
+{% endraw %}
+
+  </div>
+  <div id="rendercontent-njk" role="tabpanel">
+
+{% raw %}
+
+```jinja2
+---
+myData:
+  key: value
+---
+{% renderFile "./_includes/blogpost.md", myData, "njk" %}
+```
+
+{% endraw %}
+
+  </div>
+  <div id="rendercontent-js" role="tabpanel">
+
+{% raw %}
+
+```js
+export const data = {
+  myData: {
+    myKey: "myValue",
+  },
+};
+export async function render(data) {
+  return await this.renderFile("./includes/blogpost.md", data.myData, "njk");
+};
+```
+
+{% endraw %}
+
+  </div>
+  <div id="rendercontent-cjs" role="tabpanel">
+
+{% raw %}
+
+```js
+module.exports.data = {
+  myData: {
+    myKey: "myValue",
+  },
+};
+module.exports.render = async function (data) {
+  return await this.renderFile("./includes/blogpost.md", data.myData, "njk");
+};
+```
+
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>
diff --git a/src/_includes/snippets/plugins/renderinstall-advanced.njk b/src/_includes/snippets/plugins/renderinstall-advanced.njk
@@ -12,6 +12,7 @@ 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?
@@ -29,6 +30,7 @@ module.exports = async 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?

diff --git a/src/_includes/snippets/plugins/rendervue.njk b/src/_includes/snippets/plugins/rendervue.njk
diff --git a/src/docs/languages/javascript.md b/src/docs/languages/javascript.md
@@ -317,13 +317,13 @@ Any universal filters or shortcodes will also be available as JavaScript Templat
 
 {% set codeContent %}
 export default function(eleventyConfig) {
-  // Universal filters (Adds to Liquid, Nunjucks, 11ty.js, and Handlebars)
+  // Universal filters (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addFilter("myFilter", function(myVariable) { /* … */ });
 
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
+  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });
 
-  // Universal Paired Shortcodes (Adds to Liquid, Nunjucks, 11ty.js, Handlebars)
+  // Universal Paired Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addPairedShortcode("pairedUser", function(content, firstName, lastName) { /* … */ });
 };
 {% endset %}
@@ -348,7 +348,7 @@ export default function (data) {
 
 ### Access to `page` data values {% addedin "0.11.0" %}
 
-If you aren’t using an arrow function, JavaScript Functions (and Nunjucks, Liquid, and Handlebars Shortcodes) will have access to Eleventy [`page` data values](/docs/data-eleventy-supplied/#page-variable-contents) without needing to pass them in as arguments.
+If you aren’t using an arrow function, JavaScript Functions (and Nunjucks, Liquid Shortcodes) will have access to Eleventy [`page` data values](/docs/data-eleventy-supplied/#page-variable-contents) without needing to pass them in as arguments.
 
 {% set codeContent %}
 export default function (eleventyConfig) {

diff --git a/src/docs/languages/liquid.md b/src/docs/languages/liquid.md
@@ -120,7 +120,7 @@ export default function(eleventyConfig) {
   // Async-friendly too
   eleventyConfig.addLiquidFilter("myAsyncLiquidFilter", async function(myVariable) { /* … */ });
 
-  // Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
+  // Universal filters (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addFilter("myFilter", function(myVariable) { /* … */ });
 };
 {% endset %}
@@ -171,7 +171,7 @@ export default function(eleventyConfig) {
   // These can be async functions too
   eleventyConfig.addLiquidShortcode("user", function(name, twitterUsername) { /* … */ });
 
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
+  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addShortcode("user", function(name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>
@@ -214,7 +214,7 @@ export default function(eleventyConfig) {
   // These can be async functions too
   eleventyConfig.addPairedLiquidShortcode("user2", function(bioContent, name, twitterUsername) { /* … */ });
 
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
+  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addPairedShortcode("user2", function(bioContent, name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>
@@ -304,7 +304,7 @@ export default function (eleventyConfig) {
 
 ### Access to `page` data values {% addedin "0.11.0" %}
 
-If you aren’t using an arrow function, Liquid Shortcodes (and Nunjucks, Handlebars, and 11ty.js JavaScript Functions) will have access to Eleventy [`page` data values](/docs/data-eleventy-supplied/#page-variable-contents) without needing to pass them in as arguments.
+If you aren’t using an arrow function, Liquid Shortcodes (and Nunjucks and 11ty.js JavaScript Functions) will have access to Eleventy [`page` data values](/docs/data-eleventy-supplied/#page-variable-contents) without needing to pass them in as arguments.
 
 {% set codeContent %}
 export default function (eleventyConfig) {

diff --git a/src/docs/languages/nunjucks.md b/src/docs/languages/nunjucks.md
@@ -86,7 +86,7 @@ export default function(eleventyConfig) {
   // Nunjucks Asynchronous Filter (read on below)
   eleventyConfig.addNunjucksAsyncFilter("myAsyncNjkFilter", function(value, callback) { /* … */ });
 
-  // Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
+  // Universal filters (Adds to Liquid, Nunjucks, and 11ty.js)
   eleventyConfig.addFilter("myFilter", function(value) { /* … */ });
 };
 {% endset %}
@@ -174,7 +174,7 @@ export default function(eleventyConfig) {
   // Nunjucks Shortcode
   eleventyConfig.addNunjucksShortcode("user", function(name, twitterUsername) { /* … */ });
 
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, JavaScript, Handlebars)
+  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addShortcode("user", function(name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>
@@ -212,7 +212,7 @@ export default function(eleventyConfig) {
   // Nunjucks Shortcode
   eleventyConfig.addPairedNunjucksShortcode("user", function(bioContent, name, twitterUsername) { /* … */ });
 
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
+  // Universal Shortcodes (Adds to Liquid, Nunjucks, 11ty.js)
   eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>

diff --git a/src/docs/plugins/i18n.md b/src/docs/plugins/i18n.md
@@ -41,7 +41,7 @@ If you don’t yet have an Eleventy project, go through the [Get Started Guide f
 
 ## Usage
 
-This plugin provides two [universal filters](/docs/filters/#universal-filters) (Nunjucks, Liquid, Handlebars, 11ty.js) and one addition to the `page` variable.
+This plugin provides two [universal filters](/docs/filters/#universal-filters) (Nunjucks, Liquid, 11ty.js) and one addition to the `page` variable.
 
 ### `page.lang`
 

diff --git a/src/docs/plugins/render.md b/src/docs/plugins/render.md
@@ -14,13 +14,13 @@ communityLinksKey: syntaxrender
 
 ## Template Compatibility
 
-This plugin adds a `renderTemplate` and `renderFile` asynchronous shortcode to:
+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, too!
+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
 
@@ -37,7 +37,7 @@ This plugin is bundled with Eleventy core so it doesn’t require additional ins
 
 ## Usage
 
-### `renderTemplate`
+### `renderTemplate` Paired Shortcode
 
 Use the `renderTemplate` paired shortcode to render a template string.
 
@@ -47,8 +47,6 @@ The content inside of the shortcode will be rendered using Markdown (`"md"`). Fr
 
 The first argument to `renderTemplate` can be any valid [`templateEngineOverride`](/docs/languages/#templateengineoverride-examples) value. You can even use `"liquid,md"` to preprocess markdown with liquid. You can use [custom template types](/docs/languages/custom/) here too.
 
-{% include "snippets/plugins/rendervue.njk" %}
-
 {% callout "info", "md" %}The one exception here is that `{% raw %}{% renderTemplate "11ty.js" %}{% endraw %}` JavaScript string templates are not yet supported—use `renderFile` below instead.{% endcallout %}
 
 #### Pass in data
@@ -59,7 +57,7 @@ Both the [`eleventy`](/docs/data-eleventy-supplied/#eleventy-variable) and [`pag
 
 Outputs `myValue`.
 
-### `renderFile`
+### `renderFile` Shortcode
 
 Use the `renderFile` shortcode to render an include file.
 
@@ -82,3 +80,26 @@ The syntax is normally inferred using the file extension, but it can be overridd
 {% include "snippets/plugins/renderfileoverride.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:
+
+{% raw %}
+```yaml
+---
+myContent: "{{ 'Second' }}"
+---
+{% renderTemplate %}{{ myContent }}{% endrenderTemplate %} from renderTemplate
+{{ myContent | renderContent("njk") }} from renderContent
+```
+
+Outputs:
+
+```
+{{ 'Second' }} from renderTemplate
+Second from renderContent
+```
+{% endraw %}
diff --git a/src/docs/shortcodes.md b/src/docs/shortcodes.md
@@ -29,8 +29,8 @@ export default function (eleventyConfig) {
   // * Markdown
   // * Liquid
   // * Nunjucks
-  // * Handlebars (not async)
   // * JavaScript
+  // * Handlebars (not async)
 
   eleventyConfig.addShortcode("user", function(firstName, lastName) { /* … */ });
 
@@ -70,8 +70,8 @@ export default function (eleventyConfig) {
   // * Markdown
   // * Liquid
   // * Nunjucks
-  // * Handlebars (not async)
   // * JavaScript
+  // * Handlebars (sync only)
 
   eleventyConfig.addPairedShortcode("user", function(content, firstName, lastName) { /* … */ });