From 0119caead06a012eac84c292c16576e795b5ea35 Mon Sep 17 00:00:00 2001 From: Zach Leatherman Date: Tue, 24 Sep 2024 17:20:03 -0500 Subject: [PATCH] Passthrough copy, filters, ignores ESM docs https://github.com/11ty/eleventy/issues/836 --- .../snippets/config/ignores-nodemod.njk | 33 +++++ .../snippets/config/ignores-optout.njk | 25 ++++ src/_includes/snippets/config/ignores.njk | 27 +++++ src/_includes/snippets/copy/advanced.njk | 37 ++++++ src/_includes/snippets/copy/copy-emulate.njk | 27 +++++ src/_includes/snippets/copy/copy-ext.njk | 31 +++++ src/_includes/snippets/copy/copy-globs.njk | 27 +++++ src/_includes/snippets/copy/copy-input.njk | 33 +++++ src/_includes/snippets/copy/copy-mix.njk | 33 +++++ src/_includes/snippets/copy/copy-output.njk | 45 +++++++ src/_includes/snippets/copy/copy.njk | 47 ++++++++ src/_includes/snippets/filters/async.njk | 51 ++++++++ src/_includes/snippets/filters/filterdata.njk | 33 +++++ src/_includes/snippets/filters/filters.njk | 31 +++++ src/_includes/snippets/filters/getfilter.njk | 29 +++++ src/_includes/snippets/filters/perengine.njk | 53 ++++++++ src/docs/copy.md | 114 ++---------------- src/docs/filters.md | 92 +++----------- src/docs/ignores.md | 27 +---- 19 files changed, 588 insertions(+), 207 deletions(-) create mode 100644 src/_includes/snippets/config/ignores-nodemod.njk create mode 100644 src/_includes/snippets/config/ignores-optout.njk create mode 100644 src/_includes/snippets/config/ignores.njk create mode 100644 src/_includes/snippets/copy/advanced.njk create mode 100644 src/_includes/snippets/copy/copy-emulate.njk create mode 100644 src/_includes/snippets/copy/copy-ext.njk create mode 100644 src/_includes/snippets/copy/copy-globs.njk create mode 100644 src/_includes/snippets/copy/copy-input.njk create mode 100644 src/_includes/snippets/copy/copy-mix.njk create mode 100644 src/_includes/snippets/copy/copy-output.njk create mode 100644 src/_includes/snippets/copy/copy.njk create mode 100644 src/_includes/snippets/filters/async.njk create mode 100644 src/_includes/snippets/filters/filterdata.njk create mode 100644 src/_includes/snippets/filters/filters.njk create mode 100644 src/_includes/snippets/filters/getfilter.njk create mode 100644 src/_includes/snippets/filters/perengine.njk diff --git a/src/_includes/snippets/config/ignores-nodemod.njk b/src/_includes/snippets/config/ignores-nodemod.njk new file mode 100644 index 0000000000..538063c2fc --- /dev/null +++ b/src/_includes/snippets/config/ignores-nodemod.njk @@ -0,0 +1,33 @@ +{%- set tabid = "ignoresnodemod" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // in Eleventy 2.0 + eleventyConfig.ignores.delete("**/node_modules/**"); + + // in Eleventy 1.0 + eleventyConfig.ignores.delete("node_modules/**"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // in Eleventy 2.0 + eleventyConfig.ignores.delete("**/node_modules/**"); + + // in Eleventy 1.0 + eleventyConfig.ignores.delete("node_modules/**"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/config/ignores-optout.njk b/src/_includes/snippets/config/ignores-optout.njk new file mode 100644 index 0000000000..e65b0f5f71 --- /dev/null +++ b/src/_includes/snippets/config/ignores-optout.njk @@ -0,0 +1,25 @@ +{%- set tabid = "ignoresoptout" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.setUseGitIgnore(false); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.setUseGitIgnore(false); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/config/ignores.njk b/src/_includes/snippets/config/ignores.njk new file mode 100644 index 0000000000..a98460d3d6 --- /dev/null +++ b/src/_includes/snippets/config/ignores.njk @@ -0,0 +1,27 @@ +{%- set tabid = "ignores" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.ignores.add("README.md"); + eleventyConfig.ignores.delete("README.md"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.ignores.add("README.md"); + eleventyConfig.ignores.delete("README.md"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/advanced.njk b/src/_includes/snippets/copy/advanced.njk new file mode 100644 index 0000000000..1c489cb888 --- /dev/null +++ b/src/_includes/snippets/copy/advanced.njk @@ -0,0 +1,37 @@ +{%- set tabid = "copyadv" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.addPassthroughCopy("img", { + expand: true, // expand symbolic links + }); + + eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }, { + debug: true, // log debug information + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.addPassthroughCopy("img", { + expand: true, // expand symbolic links + }); + + eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }, { + debug: true, // log debug information + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-emulate.njk b/src/_includes/snippets/copy/copy-emulate.njk new file mode 100644 index 0000000000..c72fc18773 --- /dev/null +++ b/src/_includes/snippets/copy/copy-emulate.njk @@ -0,0 +1,27 @@ +{%- set tabid = "copyemu" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // the default is "copy" + eleventyConfig.setServerPassthroughCopyBehavior("passthrough"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // the default is "copy" + eleventyConfig.setServerPassthroughCopyBehavior("passthrough"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-ext.njk b/src/_includes/snippets/copy/copy-ext.njk new file mode 100644 index 0000000000..47b60ad9ca --- /dev/null +++ b/src/_includes/snippets/copy/copy-ext.njk @@ -0,0 +1,31 @@ +{%- set tabid = "copyext" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.setTemplateFormats([ + "md", + "css", // css is not yet a recognized template extension in Eleventy + ]); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.setTemplateFormats([ + "md", + "css", // css is not yet a recognized template extension in Eleventy + ]); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-globs.njk b/src/_includes/snippets/copy/copy-globs.njk new file mode 100644 index 0000000000..2963ac5f88 --- /dev/null +++ b/src/_includes/snippets/copy/copy-globs.njk @@ -0,0 +1,27 @@ +{%- set tabid = "copyglobs" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Find and copy any `jpg` files, maintaining directory structure. + eleventyConfig.addPassthroughCopy("**/*.jpg"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Find and copy any `jpg` files, maintaining directory structure. + eleventyConfig.addPassthroughCopy("**/*.jpg"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-input.njk b/src/_includes/snippets/copy/copy-input.njk new file mode 100644 index 0000000000..c92f5157e4 --- /dev/null +++ b/src/_includes/snippets/copy/copy-input.njk @@ -0,0 +1,33 @@ +{%- set tabid = "copyinput" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Input directory: src + // Output directory: _site + + // The following copies to `_site/img` + eleventyConfig.addPassthroughCopy("src/img"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Input directory: src + // Output directory: _site + + // The following copies to `_site/img` + eleventyConfig.addPassthroughCopy("src/img"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-mix.njk b/src/_includes/snippets/copy/copy-mix.njk new file mode 100644 index 0000000000..ad8754811b --- /dev/null +++ b/src/_includes/snippets/copy/copy-mix.njk @@ -0,0 +1,33 @@ +{%- set tabid = "copymix" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Output directory: _site + + // Find and copy any `jpg` files in any folder to _site/img + // Does not keep the same directory structure. + eleventyConfig.addPassthroughCopy({ "**/*.jpg": "img" }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Output directory: _site + + // Find and copy any `jpg` files in any folder to _site/img + // Does not keep the same directory structure. + eleventyConfig.addPassthroughCopy({ "**/*.jpg": "img" }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy-output.njk b/src/_includes/snippets/copy/copy-output.njk new file mode 100644 index 0000000000..008b157120 --- /dev/null +++ b/src/_includes/snippets/copy/copy-output.njk @@ -0,0 +1,45 @@ +{%- set tabid = "copyout" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Input directory: src + // Output directory: _site + + // Copy `img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }); + + // Copy `src/img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ "src/img": "subfolder/img" }); + + // Copy `random-folder/img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ "random-folder/img": "subfolder/img" }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Input directory: src + // Output directory: _site + + // Copy `img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }); + + // Copy `src/img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ "src/img": "subfolder/img" }); + + // Copy `random-folder/img/` to `_site/subfolder/img` + eleventyConfig.addPassthroughCopy({ "random-folder/img": "subfolder/img" }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/copy/copy.njk b/src/_includes/snippets/copy/copy.njk new file mode 100644 index 0000000000..2abce0b073 --- /dev/null +++ b/src/_includes/snippets/copy/copy.njk @@ -0,0 +1,47 @@ +{%- set tabid = "copy" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Output directory: _site + + // Copy `img/` to `_site/img` + eleventyConfig.addPassthroughCopy("img"); + + // Copy `css/fonts/` to `_site/css/fonts` + // Keeps the same directory structure. + eleventyConfig.addPassthroughCopy("css/fonts"); + + // Copy any .jpg file to `_site`, via Glob pattern + // Keeps the same directory structure. + eleventyConfig.addPassthroughCopy("**/*.jpg"); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Output directory: _site + + // Copy `img/` to `_site/img` + eleventyConfig.addPassthroughCopy("img"); + + // Copy `css/fonts/` to `_site/css/fonts` + // Keeps the same directory structure. + eleventyConfig.addPassthroughCopy("css/fonts"); + + // Copy any .jpg file to `_site`, via Glob pattern + // Keeps the same directory structure. + eleventyConfig.addPassthroughCopy("**/*.jpg"); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/filters/async.njk b/src/_includes/snippets/filters/async.njk new file mode 100644 index 0000000000..56a7343639 --- /dev/null +++ b/src/_includes/snippets/filters/async.njk @@ -0,0 +1,51 @@ +{%- set tabid = "asyncfilters" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Async universal filters add to: + // * Liquid + // * Nunjucks + // * JavaScript + + eleventyConfig.addFilter("myFilter", async function (value) { + // do some Async work + return value; + }); + + eleventyConfig.addAsyncFilter("myFilter", async function (value) { + // do some Async work + return value; + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Async universal filters add to: + // * Liquid + // * Nunjucks + // * JavaScript + + eleventyConfig.addFilter("myFilter", async function (value) { + // do some Async work + return value; + }); + + eleventyConfig.addAsyncFilter("myFilter", async function (value) { + // do some Async work + return value; + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/filters/filterdata.njk b/src/_includes/snippets/filters/filterdata.njk new file mode 100644 index 0000000000..e7f90adaa7 --- /dev/null +++ b/src/_includes/snippets/filters/filterdata.njk @@ -0,0 +1,33 @@ +{%- set tabid = "filterdata" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Make sure you’re not using an arrow function here: () => {} + eleventyConfig.addFilter("myFilter", function () { + // this.page + // this.eleventy + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Make sure you’re not using an arrow function here: () => {} + eleventyConfig.addFilter("myFilter", function () { + // this.page + // this.eleventy + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/filters/filters.njk b/src/_includes/snippets/filters/filters.njk new file mode 100644 index 0000000000..661df15723 --- /dev/null +++ b/src/_includes/snippets/filters/filters.njk @@ -0,0 +1,31 @@ +{%- set tabid = "filters" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.addFilter("makeUppercase", function(value) { … }); + + // New in {{ "2.0.0-canary.15" | coerceVersion }} + eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { … }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.addFilter("makeUppercase", function(value) { … }); + + // New in {{ "2.0.0-canary.15" | coerceVersion }} + eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { … }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/filters/getfilter.njk b/src/_includes/snippets/filters/getfilter.njk new file mode 100644 index 0000000000..1810a46689 --- /dev/null +++ b/src/_includes/snippets/filters/getfilter.njk @@ -0,0 +1,29 @@ +{%- set tabid = "getfilter" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.addShortcode("myCustomImage", function (url, alt) { + return `${alt}`; + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.addShortcode("myCustomImage", function (url, alt) { + return `${alt}`; + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/filters/perengine.njk b/src/_includes/snippets/filters/perengine.njk new file mode 100644 index 0000000000..8dc6e8944c --- /dev/null +++ b/src/_includes/snippets/filters/perengine.njk @@ -0,0 +1,53 @@ +{%- set tabid = "perengine" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Liquid Filter (async-friendly) + eleventyConfig.addLiquidFilter("myFilter", async function(value) { … }); + + // Nunjucks Filter + eleventyConfig.addNunjucksFilter("myFilter", function(value) { … }); + + // Nunjucks Async Filter + // 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) { … }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Liquid Filter (async-friendly) + eleventyConfig.addLiquidFilter("myFilter", async function(value) { … }); + + // Nunjucks Filter + eleventyConfig.addNunjucksFilter("myFilter", function(value) { … }); + + // Nunjucks Async Filter + // 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) { … }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/docs/copy.md b/src/docs/copy.md index 18f2aebd57..880c28cc9b 100644 --- a/src/docs/copy.md +++ b/src/docs/copy.md @@ -17,24 +17,7 @@ If we want to copy additional files that are not Eleventy templates, we use a fe Use a configuration API method to specify _files_ or _directories_ for Eleventy to copy. -{% codetitle ".eleventy.js" %}{% codetitle "_site", "Output Directory" %} - -```js -module.exports = function (eleventyConfig) { - // Output directory: _site - - // Copy `img/` to `_site/img` - eleventyConfig.addPassthroughCopy("img"); - - // Copy `css/fonts/` to `_site/css/fonts` - // Keeps the same directory structure. - eleventyConfig.addPassthroughCopy("css/fonts"); - - // Copy any .jpg file to `_site`, via Glob pattern - // Keeps the same directory structure. - eleventyConfig.addPassthroughCopy("**/*.jpg"); -}; -``` +{% include "snippets/copy/copy.njk" %} {% callout "info" %}Passthrough File Copy entries are relative to the root of your project and not your Eleventy input directory.{% endcallout %} @@ -51,18 +34,7 @@ For example: If we copy `src/img` using passthrough file copy, it will copy to `_site/img`. -{% codetitle ".eleventy.js" %}{% codetitle "src", "Input Directory" %} -{% codetitle "_site", "Output Directory" %} - -```js -module.exports = function (eleventyConfig) { - // Input directory: src - // Output directory: _site - - // The following copies to `_site/img` - eleventyConfig.addPassthroughCopy("src/img"); -}; -``` +{% include "snippets/copy/copy-input.njk" %} ### Using Globs {% addedin "0.9.0" %} @@ -70,14 +42,7 @@ In this example, we copy all `jpg` image files to the output folder, maintaining Note that this method is slower than non-glob methods, as it searches the entire directory structure and copies each file in Eleventy individually. -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - // Find and copy any `jpg` files, maintaining directory structure. - eleventyConfig.addPassthroughCopy("**/*.jpg"); -}; -``` +{% include "snippets/copy/copy-globs.njk" %} With an output directory of `_site`: @@ -88,40 +53,13 @@ With an output directory of `_site`: Instead of a string, pass in an object of the following structure: `{ "input": "target" }`. -{% codetitle ".eleventy.js" %}{% codetitle "src", "Input Directory" %} -{% codetitle "_site", "Output Directory" %} - -```js -module.exports = function (eleventyConfig) { - // Input directory: src - // Output directory: _site - - // Copy `img/` to `_site/subfolder/img` - eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }); - - // Copy `src/img/` to `_site/subfolder/img` - eleventyConfig.addPassthroughCopy({ "src/img": "subfolder/img" }); - - // Copy `random-folder/img/` to `_site/subfolder/img` - eleventyConfig.addPassthroughCopy({ "random-folder/img": "subfolder/img" }); -}; -``` +{% include "snippets/copy/copy-output.njk" %} #### Using Globs and Output Directories Note that this method is slower than non-glob methods, as it is searching the entire directory structure and copies each file in Eleventy individually. -{% codetitle ".eleventy.js" %}{% codetitle "_site", "Output Dir" %} - -```js -module.exports = function (eleventyConfig) { - // Output directory: _site - - // Find and copy any `jpg` files in any folder to _site/img - // Does not keep the same directory structure. - eleventyConfig.addPassthroughCopy({ "**/*.jpg": "img" }); -}; -``` +{% include "snippets/copy/copy-mix.njk" %} With an output directory of `_site`: @@ -134,16 +72,7 @@ Eleventy, by default, searches for any file in the input directory with a file e If a file format is not recognized by Eleventy as a template file extension, Eleventy will ignore the file. You can modify this behavior by adding supported template formats: -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - eleventyConfig.setTemplateFormats([ - "md", - "css", // css is not yet a recognized template extension in Eleventy - ]); -}; -``` +{% include "snippets/copy/copy-ext.njk" %} In the above code sample `css` is not currently a recognized Eleventy template, but Eleventy will search for any `*.css` files inside of the input directory and copy them to output (keeping directory structure). @@ -161,14 +90,7 @@ Practically speaking, this means that (during `--serve` only!) files are referen You can enable this behavior in your project using this configuration API method: -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - // the default is "copy" - eleventyConfig.setServerPassthroughCopyBehavior("passthrough"); -}; -``` +{% include "snippets/copy/copy-emulate.njk" %} This behavior will revert to `"copy"` in your project automatically if: @@ -185,27 +107,7 @@ This behavior will revert to `"copy"` in your project automatically if: Additionally, you can pass additional configuration options to the `recursive-copy` package. This unlocks the use passthrough file copy with symlinks, transforming or renaming copied files. Here are just a few examples: -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - eleventyConfig.addPassthroughCopy("img", { - expand: true, // expand symbolic links - }); -}; -``` - -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - let copyOptions = { - debug: true, // log debug information - }; - - eleventyConfig.addPassthroughCopy({ img: "subfolder/img" }, copyOptions); -}; -``` +{% include "snippets/copy/advanced.njk" %} Review the [full list of options on the `recursive-copy` GitHub repository](https://github.com/timkendrick/recursive-copy#usage). diff --git a/src/docs/filters.md b/src/docs/filters.md index ad9f745571..e9ca40c11d 100644 --- a/src/docs/filters.md +++ b/src/docs/filters.md @@ -22,8 +22,8 @@ A filter is a function which can be used within templating syntax to Various template engines can be extended with custom filters to modify content. Here are a few examples: - - {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "filter", additions: "hbs"} %} + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "filter"} %}
{% codetitle "sample.njk" %} {%- highlight "html" %}{% raw %} @@ -39,32 +39,25 @@ Various template engines can be extended with custom filters to modify content.
{% codetitle "sample.11ty.js" %} {%- highlight "js" %}{% raw %} -module.exports = function({name}) { +export default function({name}) { return `

${this.makeUppercase(name)}

`; }; {% endraw %}{% endhighlight %}
-
- {% codetitle "sample.hbs" %} -{%- highlight "html" %}{% raw %} -

{{ makeUppercase name }}

-{% endraw %}{%- endhighlight %} +
+ {% codetitle "sample.11ty.cjs" %} +{%- highlight "js" %}{% raw %} +module.exports = function({name}) { + return `

${this.makeUppercase(name)}

`; +}; +{% endraw %}{% endhighlight %}
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. -{% codetitle ".eleventy.js" %} - -```js -module.exports = function(eleventyConfig) { - eleventyConfig.addFilter("makeUppercase", function(value) { … }); - - // New in {{ "2.0.0-canary.15" | coerceVersion }} - eleventyConfig.addAsyncFilter("makeUppercase", async function(value) { … }); -}; -``` +{% include "snippets/filters/filters.njk" %} {% callout "info" %} Markdown files are pre-processed as Liquid templates by default—any filters available in Liquid templates are also available in Markdown files. Likewise, if you change the template engine for Markdown files, the filters available for that templating language will also be available in Markdown files. @@ -84,38 +77,13 @@ We also provide a few universal filters, built-in: If you’d like to reuse existing filters, you can use the Configuration API’s `getFilter` method. When called with a valid filter name, it will return that filter’s callback function. It can be helpful when aliasing a filter to a different name, using a filter inside of your own filter, or using a filter inside of a shortcode. -```js -module.exports = function (eleventyConfig) { - eleventyConfig.addShortcode("myCustomImage", function (url, alt) { - return `${alt}`; - }); -}; -``` +{% include "snippets/filters/getfilter.njk" %} ## 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._ -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - // Async universal filters add to: - // * Liquid - // * Nunjucks - // * JavaScript - - eleventyConfig.addFilter("myFilter", async function (value) { - // do some Async work - return value; - }); - - eleventyConfig.addAsyncFilter("myFilter", async function (value) { - // do some Async work - return value; - }); -}; -``` +{% include "snippets/filters/async.njk" %}
{%- youtubeEmbed "hJAtWQ9nmKU", "Universal Asynchronous Filters (Nunjucks improvement) (Changelog №17)", "774" -%} @@ -128,43 +96,13 @@ A few Eleventy-specific data properties are available to filter callbacks. - `this.page` {% addedin "2.0.0-canary.19" %} - `this.eleventy` {% addedin "2.0.0-canary.19" %} -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - // Make sure you’re not using an arrow function here: () => {} - eleventyConfig.addFilter("myFilter", function () { - // this.page - // this.eleventy - }); -}; -``` +{% include "snippets/filters/filterdata.njk" %} ## Per-Engine filters Filters can also be specified individually for one or more template engines. (The `addFilter` function is actually an alias for calling all of these functions.) -{% codetitle ".eleventy.js" %} - -```js -module.exports = function(eleventyConfig) { - // Liquid Filter (async-friendly) - eleventyConfig.addLiquidFilter("myFilter", async function(value) { … }); - - // Nunjucks Filter - eleventyConfig.addNunjucksFilter("myFilter", function(value) { … }); - - // Nunjucks Async Filter - // 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) { … }); -}; -``` +{% include "snippets/filters/perengine.njk" %} Note that [Nunjucks `addNunjucksAsyncFilter`](/docs/languages/nunjucks/#asynchronous-nunjucks-filters) requires the use of callbacks for async behavior. Make sure you read up on it! diff --git a/src/docs/ignores.md b/src/docs/ignores.md index 248d3efdda..ac25eb574f 100644 --- a/src/docs/ignores.md +++ b/src/docs/ignores.md @@ -27,12 +27,7 @@ You can programmatically add and delete ignores in your configuration file. `ele The `ignores` Set starts with a default `**/node_modules/**` entry in Eleventy v2.0 (it was `node_modules/**` in v1.0). -```js -module.exports = function (eleventyConfig) { - eleventyConfig.ignores.add("README.md"); - eleventyConfig.ignores.delete("README.md"); -}; -``` +{% include "snippets/config/ignores.njk" %} {% addedin "2.0.0-canary.18" %}These were decoupled from the [ignores used for the file watcher](/docs/watch-serve/#ignore-watching-files). @@ -52,17 +47,7 @@ Paths listed in your project’s `.gitignore` file are automatically ignored. Yo If you want to opt-out and search for templates inside of your `node_modules` folder, delete the entry using the Configuration API: -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - // in Eleventy 2.0 - eleventyConfig.ignores.delete("**/node_modules/**"); - - // in Eleventy 1.0 - eleventyConfig.ignores.delete("node_modules/**"); -}; -``` +{% include "snippets/config/ignores-nodemod.njk" %} {% callout "info", "md" %}The `node_modules` behavior changed in Eleventy `1.0`. If you’re still using [Eleventy `0.x`, read the `0.x` documentation](https://v0-12-1.11ty.dev/docs/ignores/#node_modules-exemption).{% endcallout %} @@ -86,12 +71,6 @@ We look for ignores in these files. Entries are relative to the ignore file’s You can disable automatic use of your `.gitignore` file by using the Configuration API method: `eleventyConfig.setUseGitIgnore(false);`. -{% codetitle ".eleventy.js" %} - -```js -module.exports = function (eleventyConfig) { - eleventyConfig.setUseGitIgnore(false); -}; -``` +{% include "snippets/config/ignores-optout.njk" %} When using `.gitignore` is disabled, `.eleventyignore` will be the single source of truth for ignored files. This also means that your `node_modules` directory will be processed unless otherwise specified in your `.eleventyignore` file.