ESM docs for preprocessors, custom tags, dev servers, events, shortco…

…des, and transforms 11ty/eleventy#836

eleventy.config.js

@@ -406,6 +406,14 @@ export default async function (eleventyConfig) {
 		}
 	});
 
+	let ref = 0;
+	eleventyConfig.on("eleventy.before", () => {
+		ref = 0;
+	});
+	eleventyConfig.addShortcode("uid", () => {
+		return `id-${++ref}`;
+	});
+
 	eleventyConfig.addShortcode("image", shortcodes.image);
 	eleventyConfig.addShortcode("avatarlocalcache", shortcodes.avatar);
 	eleventyConfig.addShortcode("communityavatar", shortcodes.communityAvatar);

src/_includes/snippets/config/liquidtags.njk

@@ -0,0 +1,59 @@
+{%- set tabid = "liquidtags" %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+{% raw %}
+```js
+export default function (eleventyConfig) {
+  // Usage: {% uppercase myVar %} where myVar has a value of "alice"
+  // Usage: {% uppercase "alice" %}
+  eleventyConfig.addLiquidTag("uppercase", function (liquidEngine) {
+    return {
+      parse: function (tagToken, remainingTokens) {
+        this.str = tagToken.args; // myVar or "alice"
+      },
+      render: async function (scope, hash) {
+        // Resolve variables
+        var str = await this.liquid.evalValue(this.str, scope); // "alice"
+
+        // Do the uppercasing
+        return str.toUpperCase(); // "ALICE"
+      },
+    };
+  });
+};
+```
+{% endraw %}
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+{% raw %}
+```js
+module.exports = function (eleventyConfig) {
+  // Usage: {% uppercase myVar %} where myVar has a value of "alice"
+  // Usage: {% uppercase "alice" %}
+  eleventyConfig.addLiquidTag("uppercase", function (liquidEngine) {
+    return {
+      parse: function (tagToken, remainingTokens) {
+        this.str = tagToken.args; // myVar or "alice"
+      },
+      render: async function (scope, hash) {
+        // Resolve variables
+        var str = await this.liquid.evalValue(this.str, scope); // "alice"
+
+        // Do the uppercasing
+        return str.toUpperCase(); // "ALICE"
+      },
+    };
+  });
+};
+```
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/config/nunjuckstags.njk

@@ -0,0 +1,73 @@
+{%- set tabid = "njktags" %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+{% raw %}
+```js
+export default function (eleventyConfig) {
+  // Usage: {% uppercase myVar %} where myVar has a value of "alice"
+  // Usage: {% uppercase "alice" %}
+  eleventyConfig.addNunjucksTag("uppercase", function (nunjucksEngine) {
+    return new (function () {
+      this.tags = ["uppercase"];
+
+      this.parse = function (parser, nodes, lexer) {
+        var tok = parser.nextToken();
+
+        var args = parser.parseSignature(null, true);
+        parser.advanceAfterBlockEnd(tok.value);
+
+        return new nodes.CallExtensionAsync(this, "run", args);
+      };
+
+      this.run = function (context, myStringArg, callback) {
+        let ret = new nunjucksEngine.runtime.SafeString(
+          myStringArg.toUpperCase()
+        );
+        callback(null, ret);
+      };
+    })();
+  });
+};
+```
+{% endraw %}
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+{% raw %}
+```js
+module.exports = function (eleventyConfig) {
+  // Usage: {% uppercase myVar %} where myVar has a value of "alice"
+  // Usage: {% uppercase "alice" %}
+  eleventyConfig.addNunjucksTag("uppercase", function (nunjucksEngine) {
+    return new (function () {
+      this.tags = ["uppercase"];
+
+      this.parse = function (parser, nodes, lexer) {
+        var tok = parser.nextToken();
+
+        var args = parser.parseSignature(null, true);
+        parser.advanceAfterBlockEnd(tok.value);
+
+        return new nodes.CallExtensionAsync(this, "run", args);
+      };
+
+      this.run = function (context, myStringArg, callback) {
+        let ret = new nunjucksEngine.runtime.SafeString(
+          myStringArg.toUpperCase()
+        );
+        callback(null, ret);
+      };
+    })();
+  });
+};
+```
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/config/preprocessors-drafts.njk

@@ -0,0 +1,33 @@
+{%- set tabid = "preprocessors-drafts" %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+```js
+export default function (eleventyConfig) {
+  eleventyConfig.addPreprocessor("drafts", "*", (data, content) => {
+		if(data.draft && process.env.ELEVENTY_RUN_MODE === "build") {
+			return false;
+		}
+	});
+};
+```
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+```js
+module.exports = function (eleventyConfig) {
+  eleventyConfig.addPreprocessor("drafts", "*", (data, content) => {
+		if(data.draft && process.env.ELEVENTY_RUN_MODE === "build") {
+			return false;
+		}
+	});
+};
+```
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/config/preprocessors.njk

@@ -0,0 +1,45 @@
+{%- set tabid = "preprocessors" %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+```js
+export default function (eleventyConfig) {
+  eleventyConfig.addPreprocessor("drafts", "njk,md,liquid", (data, content) => {
+		if(data.draft) {
+			// Ignore this file.
+			return false;
+		}
+
+		// You can also modify the raw input of the template here too, be careful!
+		return `${content}<!-- Template file: {{ page.inputPath }} -->`;
+
+		// If you return nothing or `undefined`, no changes will be made to this template.
+	});
+};
+```
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+```js
+module.exports = function (eleventyConfig) {
+  eleventyConfig.addPreprocessor("drafts", "njk,md,liquid", (data, content) => {
+		if(data.draft) {
+			// Ignore this file.
+			return false;
+		}
+
+		// You can also modify the raw input of the template here too, be careful!
+		return `${content}<!-- Template file: {{ page.inputPath }} -->`;
+
+		// If you return nothing or `undefined`, no changes will be made to this template.
+	});
+};
+```
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/config/transforms.njk

@@ -0,0 +1,52 @@
+{# uses tabContent #}
+{% set tabid %}tab-{% uid %}{% endset %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+  {% highlight "js" %}
+import htmlmin from "html-minifier-terser";
+
+export default function (eleventyConfig) {
+	eleventyConfig.addTransform("htmlmin", function (content) {
+		if ((this.page.outputPath || "").endsWith(".html")) {
+			let minified = htmlmin.minify(content, {
+				useShortDoctype: true,
+				removeComments: true,
+				collapseWhitespace: true,
+			});
+
+			return minified;
+		}
+
+		// If not an HTML output, return content as-is
+		return content;
+	});
+};
+  {% endhighlight %}
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+  {% highlight "js" %}
+const htmlmin = require("html-minifier-terser");
+
+module.exports = function (eleventyConfig) {
+	eleventyConfig.addTransform("htmlmin", function (content) {
+		if ((this.page.outputPath || "").endsWith(".html")) {
+			let minified = htmlmin.minify(content, {
+				useShortDoctype: true,
+				removeComments: true,
+				collapseWhitespace: true,
+			});
+
+			return minified;
+		}
+
+		// If not an HTML output, return content as-is
+		return content;
+	});
+};
+  {% endhighlight %}
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/configDefinition.njk

@@ -0,0 +1,22 @@
+{# uses configCodeContent #}
+{% set tabid %}tab-{% uid %}{% endset %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+  {% highlight "js" %}
+export default function (eleventyConfig) {
+{{- configCodeContent | safe -}}
+};
+  {% endhighlight %}
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+  {% highlight "js" %}
+module.exports = function (eleventyConfig) {
+{{- configCodeContent | safe -}}
+};
+  {% endhighlight %}
+  </div>
+</seven-minute-tabs>
+</is-land>