Docs for 11ty/eleventy#3124

eleventy.config.js

@@ -419,8 +419,9 @@ export default async function (eleventyConfig) {
 	eleventyConfig.addFilter("esmToCjs", memoize((sourceCode) => {
 		try {
 			let it = new ImportTransformer(sourceCode);
-
 			let outputCode = it.transformToRequire();
+
+			// lol
 			return outputCode.replace("export default ", "module.exports = ");
 		} catch(e) {
 			console.log( sourceCode );

src/_includes/layouts/base.njk

@@ -12,7 +12,7 @@ let domain = process.env.URL || "https://www.11ty.dev";
 // For things that rely on the data cascade
 let eleventyComputed = {
 	title: function(data) {
-		return data.newstitle || data.searchTitle || data.relatedTitle || data.tiptitle || data.eleventyNavigation?.key || data.title || data.headerTitle;
+		return data.newstitle || data.searchTitle || data.tiptitle || data.eleventyNavigation?.key || data.title || data.headerTitle;
 	},
 	social: {
 		imgsrc: function({ domain, page, ogimageOverride }) {

src/_includes/layouts/docs.njk

@@ -6,7 +6,7 @@ headerTag: div
 ---
 {% if eleventyNavigation and eleventyNavigation.parent %}
 <nav class="breadcrumb" aria-labelledby="breadcrumb">
-  <h2 class="sr-only" id="breadcrumb">Breadcrumbs: </h2>
+  <div class="sr-only" id="breadcrumb">Breadcrumbs: </div>
   {{ collections.sidebarNav | eleventyNavigationBreadcrumb(eleventyNavigation.parent, {includeSelf: true}) | eleventyNavigationToHtml({ listClass: 'fl fl-inline', activeListItemClass: 'breadcrumb-active' }) | safe }}
 </nav>
 {% endif %}

src/_includes/layouts/langs.njk

@@ -16,10 +16,8 @@ layout: layouts/docs.njk
 }
 .elv-langlist-hed {
 	margin: 0;
-	display: inline;
-	vertical-align: middle;
 	border: none;
-	font-size: 1.4em; /* 21px /15 */
+	font-weight: 700;
 }
 .elv-langlist > .inlinelist {
 	display: inline;
@@ -33,7 +31,7 @@ layout: layouts/docs.njk
 <h1>{{ eleventyNavigation.key }}{% if addedInVersion %}{% addedin addedInVersion%}{% endif %}</h1>
 
 <div class="elv-langlist" data-pagefind-ignore>
-<h2 class="elv-langlist-hed">Template Languages:</h2>
+	<span class="elv-langlist-hed">Template Languages:</span>
 {% templatelangs templatetypes, page %}
 </div>
 

src/docs/custom-tags.md

@@ -9,7 +9,6 @@ tags:
   - related-shortcodes
   - related-nunjucks
   - related-liquid
-  - related-handlebars
 ---
 
 # Custom Tags

src/docs/filters.md

@@ -9,7 +9,6 @@ tags:
   - related-shortcodes
   - related-nunjucks
   - related-liquid
-  - related-handlebars
   - related-javascript
 ---
 
@@ -55,7 +54,7 @@ module.exports = function({name}) {
 </seven-minute-tabs>
 </is-land>
 
-Filters can be added using the [Configuration API](/docs/config/#using-the-configuration-api) and are available to multiple template engines, simultaneously. They are currently supported in JavaScript {% addedin "0.7.0" %}, Markdown, Nunjucks, Liquid, Handlebars, and WebC.
+Filters can be added using the [Configuration API](/docs/config/#using-the-configuration-api) and are available to multiple template engines, simultaneously. They are currently supported in JavaScript {% addedin "0.7.0" %}, Markdown, Nunjucks, Liquid, and WebC.
 
 {% set codeContent %}
 export default function (eleventyConfig) {
@@ -72,7 +71,7 @@ Markdown files are pre-processed as Liquid templates by default—any filters av
 
 Read more about filters on the individual Template Language documentation pages:
 
-{% templatelangs templatetypes, page, ["njk", "liquid", "hbs", "11ty.js"], "#filters" %}
+{% templatelangs templatetypes, page, ["njk", "liquid", "11ty.js"], "#filters" %}
 
 ## Eleventy Provided Filters
 
@@ -95,7 +94,7 @@ export default function (eleventyConfig) {
 
 ## Asynchronous Filters {% addedin "2.0.0" %}
 
-Eleventy has added a new universal filter API for asynchronous filters and extended the currently available `addFilter` method to be async-friendly. _Note that even though Handlebars is used for synchronous filters in `addFilter`, it is excluded from asynchronous filters because Handlebars is not async-friendly._
+Eleventy has added a new universal filter API for asynchronous filters and extended the currently available `addFilter` method to be async-friendly.
 
 {% set codeContent %}
 export default function (eleventyConfig) {
@@ -155,9 +154,6 @@ export default function (eleventyConfig) {
   // Read the Nunjucks docs before using this (link below)
   eleventyConfig.addNunjucksAsyncFilter("myFilter", function() { /* … */ });
 
-  // Handlebars Filter (no async support)
-  eleventyConfig.addHandlebarsHelper("myFilter", function(value) { /* … */ });
-
   // JavaScript Template Function (async-friendly)
   eleventyConfig.addJavaScriptFunction("myFilter", async function(value) { /* … */ });
 };

src/docs/languages/ejs.md

@@ -14,32 +14,39 @@ layout: layouts/langs.njk
 
 You can override a `.ejs` file’s template engine. Read more at [Changing a Template’s Rendering Engine](/docs/languages/).
 
-## EJS Options
+## Installation
 
-### Optional: Compile/Render Options {% addedin "0.3.0" %}
+The `ejs` templating language was moved out of Eleventy core in v3 and now requires a plugin installation.
 
-See “Options” on the [EJS home page](https://ejs.co/).
+Add to your configuration file:
 
 {% set codeContent %}
+import ejsPlugin from "@11ty/eleventy-plugin-ejs";
+
 export default function (eleventyConfig) {
-	eleventyConfig.setEjsOptions({
-		// use <? ?> instead of <% %>
-		delimiter: "?",
-	});
-};
+	eleventyConfig.addPlugin(ejsPlugin);
+}
 {% endset %}
 {% include "snippets/configDefinition.njk" %}
 
-### Optional: Set your own Library instance {% addedin "0.3.0" %}
 
-As an escape mechanism for advanced usage, pass in your own instance of the EJS library using the Configuration API.
+Use more `ejs` options ([full options list](https://github.com/mde/ejs#options)):
 
 {% set codeContent %}
 import ejs from "ejs";
+import ejsPlugin from "@11ty/eleventy-plugin-ejs";
 
 export default function (eleventyConfig) {
-	eleventyConfig.setLibrary("ejs", ejs);
-};
+	eleventyConfig.addPlugin(ejsPlugin, {
+		async: false, // default
+
+		// use <? ?> instead of <% %>
+		delimiter: "?",
+
+		// Override the `ejs` library instance
+		eleventyLibraryOverride: ejs,
+	});
+}
 {% endset %}
 {% include "snippets/configDefinition.njk" %}
 

src/docs/languages/haml.md

@@ -14,18 +14,38 @@ layout: layouts/langs.njk
 
 You can override a `.haml` file’s template engine. Read more at [Changing a Template’s Rendering Engine](/docs/languages/).
 
-## HAML Options
+## Installation
 
-### Optional: Set your own Library instance {% addedin "0.3.0" %}
+The `haml` templating language was moved out of Eleventy core in v3 and now requires a plugin installation.
 
-As an escape mechanism for advanced usage, pass in your own instance of the HAML library using the Configuration API.
+
+```sh
+npm install @11ty/eleventy-plugin-haml
+```
+
+Add to your configuration file:
+
+{% set codeContent %}
+import hamlPlugin from "@11ty/eleventy-plugin-haml";
+
+export default function (eleventyConfig) {
+	eleventyConfig.addPlugin(hamlPlugin);
+}
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
+
+Use more options:
 
 {% set codeContent %}
 import haml from "hamljs";
+import hamlPlugin from "@11ty/eleventy-plugin-haml";
 
 export default function (eleventyConfig) {
-	eleventyConfig.setLibrary("haml", haml);
-};
+	eleventyConfig.addPlugin(hamlPlugin, {
+		// Override the `haml` library instance
+		eleventyLibraryOverride: haml,
+	});
+}
 {% endset %}
 {% include "snippets/configDefinition.njk" %}
 

src/docs/languages/handlebars.md

@@ -6,9 +6,7 @@ eleventyNavigation:
 relatedKey: handlebars
 relatedTitle: Template Language—Handlebars
 tags:
-  - related-filters
   - related-shortcodes
-  - related-custom-tags
 layout: layouts/langs.njk
 ---
 
@@ -20,17 +18,39 @@ layout: layouts/langs.njk
 
 You can override a `.hbs` file’s template engine. Read more at [Changing a Template’s Rendering Engine](/docs/languages/#overriding-the-template-language).
 
-## Handlebars Options
+## Installation
 
-### Optional: Set your own Library instance {% addedin "0.3.0" %}
+The `haml` templating language was moved out of Eleventy core in v3 and now requires a plugin installation.
 
-As an escape mechanism for advanced usage, pass in your own instance of the Handlebars library using the Configuration API.
+
+```sh
+npm install @11ty/eleventy-plugin-handlebars
+```
+
+Add to your configuration file (ESM version shown):
 
 {% set codeContent %}
+import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";
+
 export default function (eleventyConfig) {
-	let handlebars = require("handlebars");
-	eleventyConfig.setLibrary("hbs", handlebars);
-};
+	eleventyConfig.addPlugin(handlebarsPlugin);
+}
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
+
+
+Use more options:
+
+{% set codeContent %}
+import handlebars from "handlebars";
+import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";
+
+export default function (eleventyConfig) {
+	eleventyConfig.addPlugin(handlebarsPlugin, {
+		// Override the `ejs` library instance
+		eleventyLibraryOverride: handlebars,
+	});
+}
 {% endset %}
 {% include "snippets/configDefinition.njk" %}
 
@@ -41,72 +61,35 @@ export default function (eleventyConfig) {
 | ✅ Partials                                                       | `{% raw %}{{> user}}{% endraw %}` looks for `_includes/user.hbs`. Does not process front matter in the include file.                                                                                      |
 | 🚫 Partials (Relative Path)                                       | **Not yet supported**: `{% raw %}{{> ./user}}{% endraw %}` looks for `user.hbs` in the template’s current directory.                                                                                      |
 | ✅ Helpers (Custom Tags)                                          | `{% raw %}{{ helperName myObject }}{% endraw %}` Handlebars calls them Helpers, but Eleventy calls them Shortcodes. Read more about [Shortcodes](/docs/shortcodes/) or [Custom Tags](/docs/custom-tags/). |
-| ✅ [Eleventy Universal Filters](/docs/filters/#universal-filters) | `{% raw %}{{ filterName myObject }}{% endraw %}` Read more about [Filters](/docs/filters/).                                                                                                               |
+| ✅ [Filters](/docs/filters/) | `{% raw %}{{ filterName myObject }}{% endraw %}` Read more about [Filters](/docs/filters/).                                                                                                               |
 | ✅ [Shortcodes](/docs/shortcodes/)                                | `{% raw %}{{{ uppercase name }}}{% endraw %}` Read more about [Shortcodes](/docs/shortcodes/). {% addedin "0.5.0" %}                                                                                      |
 
-<span id="filters"></span><span id="shortcodes"></span>
-
 ## Helpers
 
-Helpers are used to transform or modify content. You can add Handlebars specific helpers, but you probably want to add a [Universal shortcode](/docs/filters/) instead.
-
-Read more about [Handlebars Helpers syntax](https://handlebarsjs.com/#helpers)
-
-{% set codeContent %}
-export default function(eleventyConfig) {
-  // Handlebars Helper
-  eleventyConfig.addHandlebarsHelper("myHandlebarsHelper", function(value) { /* … */ });
-
-  // Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
-  // Read the note about Universal Filters below: Use a shortcode instead!
-  eleventyConfig.addFilter("myFilter", function(value) { /* … */ });
-};
-{% endset %}
-{% include "snippets/configDefinition.njk" %}
-
+Helpers are used to transform or modify content.
 
-#### Usage
-
-{% raw %}
+Both Eleventy [Universal Filters](/docs/filters/) and [Universal shortcodes](/docs/shortcodes/) are exposed as Helpers in Handlebars templates.
 
-```html
-<h1>{{{ myHandlebarsHelper myVariable }}}</h1>
-```
-
-{% endraw %}
-
-{% callout "info" %}Note that if you return HTML in your Handlebars helper, you need to use the Handlebars triple-stash syntax (three opening and three closing curly brackets) to avoid double-escaped HTML.{% endcallout %}
+Read more about [Handlebars Helpers syntax](https://handlebarsjs.com/#helpers)
 
-### Asynchronous Helpers
+## Filters
 
-These are not supported by Handlebars. Read more at [this Handlebars issue](https://github.com/wycats/handlebars.js/issues/717).
+{% callout "warn", "md" %}Asynchronous filters are not supported by Handlebars. Read more at [this Handlebars issue](https://github.com/wycats/handlebars.js/issues/717).{% endcallout %}
 
 ### A note about Universal Filters
 
 Universal filters have always been funneled into Handlebars helpers. However, shortcodes (Paired/Single) match better with the semantic footprint of Handlebars Helpers.
 
-{% set codeContent %}
-export default function(eleventyConfig) {
-  // Universal filters (Adds to Liquid, Nunjucks, and Handlebars)
-  eleventyConfig.addFilter("myFilter", function(value) { /* … */ });
-};
-{% endset %}
-{% include "snippets/configDefinition.njk" %}
-
 Moving forward for Handlebars content, using Universal Shortcodes are preferred to Universal Filters. We will continue to support funneling Universal filters to Handlebars helpers. This will not affect your template content as the syntax for Handlebars filters/helpers/shortcodes will continue to be the same. They’re all just helpers.
 
 ## Shortcodes
 
-Shortcodes are basically reusable bits of content. You can add Handlebars specific shortcodes, but you probably want to add a [Universal shortcode](/docs/shortcodes/) instead.
+Shortcodes are basically reusable bits of content. Handlebars makes use of existing synchronous [Universal shortcodes](/docs/shortcodes/).
 
-### Single Shortcode
+{% callout "warn", "md" %}Asynchronous shortcodes are not supported by Handlebars. Read more at [this Handlebars issue](https://github.com/wycats/handlebars.js/issues/717).{% endcallout %}
 
 {% set codeContent %}
 export default function(eleventyConfig) {
-  // Handlebars Shortcode
-  eleventyConfig.addHandlebarsShortcode("user", function(name, twitterUsername) { /* … */ });
-
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
   eleventyConfig.addShortcode("user", function(name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>
@@ -140,12 +123,10 @@ export default function(eleventyConfig) {
 
 ### Paired Shortcode
 
+{% callout "warn", "md" %}Asynchronous shortcodes are not supported by Handlebars. Read more at [this Handlebars issue](https://github.com/wycats/handlebars.js/issues/717).{% endcallout %}
+
 {% set codeContent %}
 export default function(eleventyConfig) {
-  // Handlebars Shortcode
-  eleventyConfig.addPairedHandlebarsShortcode("user", function(bioContent, name, twitterUsername) { /* … */ });
-
-  // Universal Shortcodes (Adds to Liquid, Nunjucks, Handlebars)
   eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
     return `<div class="user">
 <div class="user_name">${name}</div>
@@ -164,8 +145,7 @@ Note that you can put any Handlebars tags or content inside the `{% raw %}{{ use
 {% raw %}
 
 ```html
-{{# user "Zach Leatherman" "zachleat" }} Zach likes to take long walks on
-Nebraska beaches. {{/ user }}
+{{# user "Zach Leatherman" "zachleat" }}Zach likes to take long walks on Nebraska beaches.{{/ user }}
 ```
 
 {% endraw %}
@@ -180,27 +160,4 @@ Nebraska beaches. {{/ user }}
 	<div class="user_twitter">@zachleat</div>
 	<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
 </div>
-```
-
-### Asynchronous Shortcodes
-
-These are not supported by Handlebars. Read more at [this Handlebars issue](https://github.com/wycats/handlebars.js/issues/717).
-
-### Access to `page` data values
-
-If you aren’t using an arrow function, Handlebars Shortcodes (and Nunjucks, Liquid, 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) {
-	eleventyConfig.addHandlebarsShortcode("myShortcode", function () {
-		// Available in 0.11.0 and above
-		console.log(this.page);
-
-		// For example:
-		console.log(this.page.url);
-		console.log(this.page.inputPath);
-		console.log(this.page.fileSlug);
-	});
-};
-{% endset %}
-{% include "snippets/configDefinition.njk" %}
+```