+{%- highlight "liquid" %}{% raw %}
+{% image "cat.jpg", "photo of my tabby cat" %}
+{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}
+{% endraw %}{% endhighlight %}
+
The comma between arguments is optional in Liquid templates.
+
+
+{%- highlight "jinja2" %}{% raw %}
+{% image "cat.jpg", "photo of my tabby cat" %}
+{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}
+{% endraw %}{% endhighlight %}
+
The comma between arguments is required in Nunjucks templates.
+
+
+{%- highlight "js" %}{% raw %}
+export default function() {
+ let img1 = await this.image("cat.jpg", "photo of my tabby cat");
+ let img2 = await this.image("cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw");
+
+ return `${img1}
+
+${img2}`;
+};
+{% endraw %}{% endhighlight %}
+
+
+{%- highlight "js" %}{% raw %}
+module.exports = function() {
+ let img1 = await this.image("cat.jpg", "photo of my tabby cat");
+ let img2 = await this.image("cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw");
+
+ return `${img1}
+
+${img2}`;
+};
+{% endraw %}{% endhighlight %}
+
+
+
+
\ No newline at end of file
diff --git a/src/_includes/snippets/plugins/i18nalternate.njk b/src/_includes/snippets/plugins/i18nalternate.njk
new file mode 100644
index 0000000000..6638bb916d
--- /dev/null
+++ b/src/_includes/snippets/plugins/i18nalternate.njk
@@ -0,0 +1,104 @@
+
+
+ {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localelinksrel"} %}
+
+
+{% codetitle "_includes/mylayout.njk" %}
+
+{% raw %}
+
+```njk
+{# `{{lang}}` must be set by you in the data cascade, see above note #}
+
+
+
+
+ {% for link in page.url | locale_links %}
+
+ {% endfor %}
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "_includes/mylayout.njk" %}
+
+{% raw %}
+
+```liquid
+
+{% comment %} `{{lang}}` must be set by you in the data cascade, see above note {% endcomment %}
+
+
+
+{% assign links = page.url | locale_links %}
+{%- for link in links %}
+
+{%- endfor -%}
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/_includes/mylayout.11ty.js" %}
+
+{% raw %}
+
+```js
+export default function (data) {
+ let links = this.locale_links(data.page.url);
+ // side note: url argument is optional for current page
+
+ // `${data.lang}` must be set by you in the data cascade, see above note
+ return `
+
+
+
+
+ ${links
+ .map((link) => {
+ return ` `;
+ })
+ .join("\n")}
+`;
+};
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/_includes/mylayout.11ty.cjs" %}
+
+{% raw %}
+
+```js
+module.exports = function (data) {
+ let links = this.locale_links(data.page.url);
+ // side note: url argument is optional for current page
+
+ // `${data.lang}` must be set by you in the data cascade, see above note
+ return `
+
+
+
+
+ ${links
+ .map((link) => {
+ return ` `;
+ })
+ .join("\n")}
+`;
+};
+```
+
+{% endraw %}
+
+
+
+{% codetitle "/en/blog.njk" %}
+
+{% raw %}
+
+```njk
+This page is also available in:
+{% for link in page.url | locale_links %}
+{%- if not loop.first %},{% endif %}
+{{link.label}}
+{% endfor %}
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/en/blog.liquid" %}
+
+{% raw %}
+
+```liquid
+This page is also available in:
+{% assign links = page.url | locale_links %}
+{%- for link in links %}
+{%- unless forloop.first %},{% endunless %}
+{{link.label}}
+{%- endfor -%}
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/en/blog.11ty.js" %}
+
+{% raw %}
+
+```js
+export default function (data) {
+ let links = this.locale_links(data.page.url);
+
+ // Don’t forget to localize this text too
+ return `This page is also available in:
+${links
+ .map((link) => {
+ return `${link.label}`;
+ })
+ .join(", ")}`;
+};
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/en/blog.11ty.cjs" %}
+
+{% raw %}
+
+```js
+module.exports = function (data) {
+ let links = this.locale_links(data.page.url);
+
+ // Don’t forget to localize this text too
+ return `This page is also available in:
+${links
+ .map((link) => {
+ return `${link.label}`;
+ })
+ .join(", ")}`;
+};
+```
+
+{% endraw %}
+
+
+
+
\ No newline at end of file
diff --git a/src/_includes/snippets/plugins/i18nlocaleurl-arg.njk b/src/_includes/snippets/plugins/i18nlocaleurl-arg.njk
new file mode 100644
index 0000000000..204e3ca7d4
--- /dev/null
+++ b/src/_includes/snippets/plugins/i18nlocaleurl-arg.njk
@@ -0,0 +1,65 @@
+
+
+ {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localeurlforce"} %}
+
+
+{% codetitle "/en/index.11ty.js" %}
+
+{% raw %}
+
+```js
+export default function (data) {
+ return `Blog`;
+ // returns Blog
+};
+```
+
+{% endraw %}
+
+{% codetitle "/es/index.11ty.js" %}
+
+{% raw %}
+
+```js
+export default function (data) {
+ return `Blog`;
+ // returns Blog
+};
+```
+
+{% endraw %}
+
+
+
+
+{% codetitle "/en/index.11ty.cjs" %}
+
+{% raw %}
+
+```js
+module.exports = function (data) {
+ return `Blog`;
+ // returns Blog
+};
+```
+
+{% endraw %}
+
+{% codetitle "/es/index.11ty.cjs" %}
+
+{% raw %}
+
+```js
+module.exports = function (data) {
+ return `Blog`;
+ // returns Blog
+};
+```
+
+{% endraw %}
+
+
+
+
\ No newline at end of file
diff --git a/src/_includes/snippets/plugins/render.njk b/src/_includes/snippets/plugins/render.njk
new file mode 100644
index 0000000000..8dea496b2e
--- /dev/null
+++ b/src/_includes/snippets/plugins/render.njk
@@ -0,0 +1,75 @@
+
+
+ {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpl"} %}
+
+
+{% raw %}
+
+```liquid
+{% renderTemplate "md" %}
+# I am a title
+
+* I am a list
+* I am a list
+{% endrenderTemplate %}
+```
+
+{% endraw %}
+
+
+
+
+{% raw %}
+
+```jinja2
+{% renderTemplate "md" %}
+# I am a title
+
+* I am a list
+* I am a list
+{% endrenderTemplate %}
+```
+
+{% endraw %}
+
+
+
+
+{% raw %}
+
+```js
+export default async function () {
+ return await this.renderTemplate(
+ `# I am a title
+
+* I am a list
+* I am a list`,
+ "md"
+ );
+};
+```
+
+{% endraw %}
+
+
+
+
+{% raw %}
+
+```js
+module.exports = async function () {
+ return await this.renderTemplate(
+ `# I am a title
+
+* I am a list
+* I am a list`,
+ "md"
+ );
+};
+```
+
+{% endraw %}
+
+
+
+
\ No newline at end of file
diff --git a/src/_includes/snippets/plugins/renderdata.njk b/src/_includes/snippets/plugins/renderdata.njk
new file mode 100644
index 0000000000..a7b2478fe8
--- /dev/null
+++ b/src/_includes/snippets/plugins/renderdata.njk
@@ -0,0 +1,77 @@
+
+
+ {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpldata"} %}
+
+
+{% raw %}
+
+```js
+export default async function () {
+ return await this.renderTemplate(
+ `
+ THIS IS VUE
+
`,
+ "vue"
+ );
+};
+```
+
+{% endraw %}
+
+
+
+
+{% raw %}
+
+```js
+module.exports = async function () {
+ return await this.renderTemplate(
+ `
+ THIS IS VUE
+
`,
+ "vue"
+ );
+};
+```
+
+{% endraw %}
+
+
+
+
\ No newline at end of file
diff --git a/src/docs/plugins.md b/src/docs/plugins.md
index d2d898d367..77c00ebea2 100644
--- a/src/docs/plugins.md
+++ b/src/docs/plugins.md
@@ -31,22 +31,22 @@ npm install @11ty/eleventy-plugin-rss --save
Your config file is probably named `.eleventy.js`.
-{% codetitle ".eleventy.js" %}
-
-```js
-const pluginRss = require("@11ty/eleventy-plugin-rss");
-module.exports = function (eleventyConfig) {
+{% set codeContent %}
+import pluginRss from "@11ty/eleventy-plugin-rss";
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(pluginRss);
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
### Plugin Configuration Options {% addedin "0.5.4" %}
Use an optional second argument to `addPlugin` to customize your plugin’s behavior. These options are specific to the plugin. Please consult the plugin’s documentation (e.g. the [`eleventy-plugin-syntaxhighlight` README](https://github.com/11ty/eleventy-plugin-syntaxhighlight/blob/master/README.md)) to learn what options are available to you.
-```js
-const pluginSyntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");
-module.exports = function (eleventyConfig) {
+{% set codeContent %}
+import pluginSyntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";
+
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(pluginSyntaxHighlight, {
// only install the markdown highlighter
templateFormats: ["md"],
@@ -56,24 +56,25 @@ module.exports = function (eleventyConfig) {
},
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
Advanced Usage: Namespacing a plugin
It’s unlikely you’ll need this feature _but_ you can namespace parts of your configuration using `eleventyConfig.namespace`. This will add a string prefix to all filters, tags, helpers, shortcodes, collections, and transforms.
-{% codetitle ".eleventy.js" %}
+{% set codeContent %}
+import pluginRss from "@11ty/eleventy-plugin-rss";
-```js
-const pluginRss = require("@11ty/eleventy-plugin-rss");
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.namespace("myPrefix_", () => {
// the rssLastUpdatedDate filter is now myPrefix_rssLastUpdatedDate
eleventyConfig.addPlugin(pluginRss);
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
{% callout "warn" %}
Plugin namespacing is an application feature and should not be used if you are creating your own plugin (in your plugin configuration code). Follow along at Issue #256.
@@ -85,13 +86,14 @@ Plugin namespacing is an application feature and should not be used if you are c
A plugin primarily provides a “configuration function.” This function is called when Eleventy is first initialized, and operates similarly to a user’s configuration function (the same `eleventyConfig` argument passed to the user’s `.eleventy.js` file is passed here), in addition to any config passed by the user:
-{% codetitle "plugin.js" %}
+
plugin.js
-```js
-module.exports = function (eleventyConfig, pluginOptions) {
+{% set codeContent %}
+export default function (eleventyConfig, pluginOptions) {
// Your plugin code goes here
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
Note that plugins run as a second stage after the user’s primary configuration file has executed (to have access to the return object values).
@@ -100,21 +102,20 @@ Note that plugins run as a second stage after the user’s primary configuration
If you want to allow developers to use custom arguments provided by your plugin, you can export an object. Prefer using the above syntax unless you need this behavior. For an example of how this is used, see the [syntax highlighting plugin](https://github.com/11ty/eleventy-plugin-syntaxhighlight/blob/23761d7fd54de0312040520175959327b1a0ab9b/.eleventy.js#L10)
-{% codetitle "fancy-plugin.js" %}
+
plugin-with-args.js
-```js
-module.exports = {
+{% set codeContent %}
+export default {
initArguments: {},
configFunction: function (eleventyConfig, pluginOptions) {
// Your plugin code goes here
},
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
-{% codetitle ".eleventy.js" %}
-
-```js
-module.exports = function (eleventyConfig) {
+{% set codeContent %}
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(require("./fancy-plugin.js"), {
init: function (initArguments) {
// `this` is the eleventyConfig object
@@ -122,7 +123,8 @@ module.exports = function (eleventyConfig) {
},
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -130,20 +132,25 @@ module.exports = function (eleventyConfig) {
If your plugin requires a specific feature in Eleventy, you should feature test it!
-```js
-module.exports = function (eleventyConfig, pluginOptions) {
+
plugin.js
+
+{% set codeContent %}
+export default function (eleventyConfig, pluginOptions) {
if(!("addTemplate" in eleventyConfig)) {
console.log( `[my-test-plugin] WARN Eleventy plugin compatibility: Virtual Templates are required for this plugin, please use Eleventy v3.0 or newer.` );
}
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
### Version Checking
If feature testing is not available for your specific use case, you can add this code to your plugin configuration to show a warning if the plugin consumer does not have a compatible version of Eleventy:
-```js
-module.exports = function (eleventyConfig, pluginOptions) {
+
plugin.js
+
+{% set codeContent %}
+export default function (eleventyConfig, pluginOptions) {
try {
// Emit a warning message if the application is not using Eleventy 3.0 or newer (including prereleases).
eleventyConfig.versionCheck(">=3.0");
@@ -151,7 +158,8 @@ module.exports = function (eleventyConfig, pluginOptions) {
console.log( `[my-test-plugin] WARN Eleventy plugin compatibility: ${e.message}` );
}
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
* This uses the [`semver` package](https://www.npmjs.com/package/semver) and is compatible with advanced range syntax.
* **Upper bounding your version number is _not recommended_**. Eleventy works very hard to maintain backwards compatibility between major versions. Please ensure your plugin code does the same!
@@ -172,8 +180,8 @@ Plugins (by default) execute in a second stage of configuration after the user
You are unlikely to need this, but you can execute a plugin’s code immediately using the `immediate` option.
-```js
-module.exports = function (eleventyConfig, pluginOptions) {
+{% set codeContent %}
+export default function (eleventyConfig, pluginOptions) {
console.log( "first" );
eleventyConfig.addPlugin(eleventyConfig => {
@@ -188,4 +196,5 @@ module.exports = function (eleventyConfig, pluginOptions) {
console.log("third");
};
-```
\ No newline at end of file
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
\ No newline at end of file
diff --git a/src/docs/plugins/fetch.md b/src/docs/plugins/fetch.md
index 1bcb21e397..915b087018 100644
--- a/src/docs/plugins/fetch.md
+++ b/src/docs/plugins/fetch.md
@@ -53,10 +53,10 @@ Formerly known as [`@11ty/eleventy-cache-assets`](https://www.npmjs.com/package/
Consider the following example, perhaps in an Eleventy [Global Data File](/docs/data-global/).
-```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+{% set codeContent %}
+import EleventyFetch from "@11ty/eleventy-fetch";
-module.exports = async function () {
+export default async function () {
let url = "https://api.github.com/repos/11ty/eleventy";
/* This returns a promise */
@@ -65,7 +65,8 @@ module.exports = async function () {
type: "json", // we’ll parse JSON for you
});
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
### Options
@@ -106,9 +107,9 @@ The `directory` option let’s you change where the cache is stored. It is stron
{% callout "warn" %}Read the Important Security and Privacy Notice.{% endcallout %}
```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+import EleventyFetch from "@11ty/eleventy-fetch";
-EleventyFetch("https://…", {
+await EleventyFetch("https://…", {
directory: ".cache",
});
```
@@ -122,9 +123,9 @@ If you want to use this utility inside of a Netlify Function (or AWS Lambda), us
- `removeUrlQueryParams: true` (`false` is default)
```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+import EleventyFetch from "@11ty/eleventy-fetch";
-EleventyFetch(
+await EleventyFetch(
"https://www.zachleat.com/img/avatar-2017-big.png?Get=rid&of=these",
{
removeUrlQueryParams: true,
@@ -140,10 +141,10 @@ Note that query params are removed before—and are relevant to how—the hash k
2. If a failure happens and a cache entry already exists (_even if it’s expired_), it will use the cached entry.
3. If you prefer the build to _fail_ when your API requests fail, leave out the `try` `catch` and let the error throw without handling it!
-```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+{% set codeContent %}
+import EleventyFetch from "@11ty/eleventy-fetch";
-module.exports = async function () {
+export default async function () {
try {
let url = "https://api.github.com/repos/11ty/eleventy";
@@ -158,7 +159,8 @@ module.exports = async function () {
};
}
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
## Running this on your Build Server
@@ -170,10 +172,10 @@ This [documentation has moved to the Deployment page](/docs/deployment/#persisti
This is what [`eleventy-img`](/docs/plugins/image/) uses internally.
-```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+{% set codeContent %}
+import EleventyFetch from "@11ty/eleventy-fetch";
-module.exports = async function () {
+export default async function () {
let url = "https://www.zachleat.com/img/avatar-2017-big.png";
let imageBuffer = await EleventyFetch(url, {
duration: "1d",
@@ -183,29 +185,32 @@ module.exports = async function () {
// (Example truncated)
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
### Fetch Google Fonts CSS
Also a good example of using `fetchOptions` to pass in a custom user agent. Full option list is available on the [`node-fetch` documentation](https://www.npmjs.com/package/node-fetch#options).
-```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
-
-let url =
- "https://fonts.googleapis.com/css?family=Roboto+Mono:400&display=swap";
-let fontCss = await EleventyFetch(url, {
- duration: "1d",
- type: "text",
- fetchOptions: {
- headers: {
- // lol
- "user-agent":
- "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36",
+{% set codeContent %}
+import EleventyFetch from "@11ty/eleventy-fetch";
+
+export default async function() {
+ let url = "https://fonts.googleapis.com/css?family=Roboto+Mono:400&display=swap";
+ let fontCss = await EleventyFetch(url, {
+ duration: "1d",
+ type: "text",
+ fetchOptions: {
+ headers: {
+ // lol
+ "user-agent":
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36",
+ },
},
- },
-});
-```
+ });
+};
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
### Fetching GitHub Stars for a repo
@@ -217,10 +222,10 @@ let fontCss = await EleventyFetch(url, {
**You probably won’t need to do this.** If you’d like to store data of your own choosing in the cache (some expensive thing, but perhaps not related to a network request), you may do so! Consider the following [Global Data File](/docs/data-global/):
-```js
-const { AssetCache } = require("@11ty/eleventy-fetch");
+{% set codeContent %}
+import { AssetCache } from "@11ty/eleventy-fetch";
-module.exports = async function () {
+export default async function () {
// Pass in your unique custom cache key
// (normally this would be tied to your API URL)
let asset = new AssetCache("zachleat_twitter_followers");
@@ -238,12 +243,13 @@ module.exports = async function () {
return fakeTwitterApiContents;
};
-```
+{% endset %}
+{% include "snippets/esmCjsTabs.njk" %}
### Change Global Concurrency
```js
-const EleventyFetch = require("@11ty/eleventy-fetch");
+import EleventyFetch from "@11ty/eleventy-fetch";
EleventyFetch.concurrency = 4; // default is 10
```
diff --git a/src/docs/plugins/i18n.md b/src/docs/plugins/i18n.md
index 2906413563..8aeacf2ad6 100644
--- a/src/docs/plugins/i18n.md
+++ b/src/docs/plugins/i18n.md
@@ -30,26 +30,25 @@ If you don’t yet have an Eleventy project, go through the [Get Started Guide f
### Add to your configuration file
-{% codetitle ".eleventy.js" %}
+{% set codeContent %}
+import { EleventyI18nPlugin } from "@11ty/eleventy";
-```js
-const { EleventyI18nPlugin } = require("@11ty/eleventy");
-
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(EleventyI18nPlugin, {
// any valid BCP 47-compatible language tag is supported
defaultLanguage: "", // Required, this site uses "en"
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
Expand to see the full list of advanced options
-```js
-const { EleventyI18nPlugin } = require("@11ty/eleventy");
+{% set codeContent %}
+import { EleventyI18nPlugin } from "@11ty/eleventy";
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(EleventyI18nPlugin, {
// any valid BCP 47-compatible language tag is supported
defaultLanguage: "", // Required, this site uses "en"
@@ -69,7 +68,8 @@ module.exports = function (eleventyConfig) {
// errorMode: "never", // don’t throw errors for missing content
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -87,115 +87,7 @@ Check out [the rest of the data available on the `page` object](/docs/data-eleve
Accepts any arbitrary URL string and transforms it using the current page’s locale. Works as expected if the URL already contains a language code. This is most useful in any shared code used by internationalized content (layouts, partials, includes, etc).
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localeurl", additions: "hbs"} %}
-
-
-{% codetitle "/en/index.11ty.js" %}
-
-{% raw %}
-
-```js
-module.exports = function (data) {
- return `Blog`;
- // returns Blog
-};
-```
-
-{% endraw %}
-
-{% codetitle "/es/index.11ty.js" %}
-
-{% raw %}
-
-```js
-module.exports = function (data) {
- return `Blog`;
- // returns Blog
-};
-```
-
-{% endraw %}
-
-
-
-
+{% include "snippets/plugins/i18nlocaleurl.njk" %}
If the link argument already has a valid language code, it will be swapped. The following all return `/en/blog/` when rendered in `/en/*` templates (or `/es/blog/` in `/es/*` templates):
@@ -212,69 +104,7 @@ It’s important to note that this filter _checks for the existence of the file_
It’s unlikely that you’ll need to but you _can_ override the root locale with a second argument:
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localeurlforce", additions: "hbs"} %}
-
-
-
+{% include "snippets/plugins/i18nlocaleurl-arg.njk" %}
### `locale_links` Filter
@@ -286,69 +116,7 @@ Returns an array of the relevant alternative content for a specified URL (or, de
#### “This page also available in:” Example
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localelinks"} %}
-
-
-{% codetitle "/en/blog.njk" %}
-
-{% raw %}
-
-```njk
-This page is also available in:
-{% for link in page.url | locale_links %}
-{%- if not loop.first %},{% endif %}
-{{link.label}}
-{% endfor %}
-```
-
-{% endraw %}
-
-
-
-
-{% codetitle "/en/blog.liquid" %}
-
-{% raw %}
-
-```liquid
-This page is also available in:
-{% assign links = page.url | locale_links %}
-{%- for link in links %}
-{%- unless forloop.first %},{% endunless %}
-{{link.label}}
-{%- endfor -%}
-```
-
-{% endraw %}
-
-
-
-
-{% codetitle "/en/blog.11ty.js" %}
-
-{% raw %}
-
-```js
-module.exports = function (data) {
- let links = this.locale_links(data.page.url);
-
- // Don’t forget to localize this text too
- return `This page is also available in:
-${links
- .map((link) => {
- return `${link.label}`;
- })
- .join(", ")}`;
-};
-```
-
-{% endraw %}
-
-
-
-
+{% include "snippets/plugins/i18nexample.njk" %}
Renders as:
@@ -364,83 +132,7 @@ The `href` attributes here must be fully qualified (include the full domain with
{% callout "info", "md" %}The top level `lang` data property used here is most commonly set by you in the data cascade. For example: `/en/en.json` with `{"lang": "en"}` and `/es/es.json` with `{"lang": "es"}`.{% endcallout %}
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "localelinksrel"} %}
-
-
-{% codetitle "_includes/mylayout.njk" %}
-
-{% raw %}
-
-```njk
-{# `{{lang}}` must be set by you in the data cascade, see above note #}
-
-
-
-
- {% for link in page.url | locale_links %}
-
- {% endfor %}
-```
-
-{% endraw %}
-
-
-
-
-{% codetitle "_includes/mylayout.njk" %}
-
-{% raw %}
-
-```liquid
-
-{% comment %} `{{lang}}` must be set by you in the data cascade, see above note {% endcomment %}
-
-
-
-{% assign links = page.url | locale_links %}
-{%- for link in links %}
-
-{%- endfor -%}
-```
-
-{% endraw %}
-
-
-
-
-{% codetitle "/_includes/mylayout.11ty.js" %}
-
-{% raw %}
-
-```js
-module.exports = function (data) {
- let links = this.locale_links(data.page.url);
- // side note: url argument is optional for current page
-
- // `${data.lang}` must be set by you in the data cascade, see above note
- return `
-
-
-
-
- ${links
- .map((link) => {
- return ` `;
- })
- .join("\n")}
-`;
-};
-```
-
-{% endraw %}
-
-
-
-
-
-
+{% include "snippets/plugins/i18nalternate.njk" %}
### Using with [`get*CollectionItem` filters](/docs/filters/collection-items/)
diff --git a/src/docs/plugins/image.md b/src/docs/plugins/image.md
index 41c38407e1..e34c7213e8 100644
--- a/src/docs/plugins/image.md
+++ b/src/docs/plugins/image.md
@@ -167,45 +167,7 @@ There are four different ways to use Eleventy Image in Eleventy projects:
{% addedin "v3.0.0-alpha.7" %}{% addedin "Image v5.0.0" %}During local development (when using `--serve`), images optimized via transform are _not_ processed at build time and instead are optimized when requested in the browser. Read more about [`transformOnRequest`](#optimize-images-on-request).
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "transform-config", only: "jscjs,jsesm"} %}
-
-
-{% codetitle ".eleventy.js" %}
-
-```js
+{% set codeContent %}
import { eleventyImageTransformPlugin } from "@11ty/eleventy-img";
export default function (eleventyConfig) {
@@ -228,12 +190,9 @@ export default function (eleventyConfig) {
decoding: "async",
},
});
-}
-```
-
-
-
-
+};
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
#### Relative paths
@@ -260,13 +219,12 @@ You can configure individual `` elements with per-instance overrides:
The examples below require an [async-friendly shortcodes](/docs/shortcodes/#asynchronous-shortcodes) (works in Nunjucks, Liquid, JavaScript, and [WebC](/docs/languages/webc/)).
-{% codetitle ".eleventy.js" %}
+
-```js
-const Image = require("@11ty/eleventy-img");
+{% set codeContent %}
+import Image from "@11ty/eleventy-img";
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addShortcode("image", async function (src, alt, widths = [300, 600], sizes = "100vh") {
let metadata = await Image(src, {
widths,
@@ -284,18 +242,16 @@ module.exports = function (eleventyConfig) {
return Image.generateHTML(metadata, imageAttributes);
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
Expand to see full options list for Image.generateHTML
-{% codetitle ".eleventy.js" %}
-
-```js
-const Image = require("@11ty/eleventy-img");
+{% set codeContent %}
+import Image from "@11ty/eleventy-img";
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addShortcode("image", async function (src, alt, widths = ["auto"], sizes = "100vh") {
let metadata = await Image(src, {
// omitted for brevity
@@ -320,7 +276,8 @@ module.exports = function (eleventyConfig) {
return Image.generateHTML(metadata, imageAttributes, options);
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -334,41 +291,7 @@ If you want to use Eleventy Image in WebC, take note that it is possible to wire
Now you can use the `image` shortcode in your templates and the appropriate HTML will be generated for you (based on your specified Image options).
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "shortcode"} %}
-
- {% codetitle "Liquid", "Syntax" %}
-{%- highlight "liquid" %}{% raw %}
-{% image "cat.jpg", "photo of my tabby cat" %}
-{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}
-{% endraw %}{% endhighlight %}
-
The comma between arguments is optional in Liquid templates.
-
-
- {% codetitle "Nunjucks", "Syntax" %}
-{%- highlight "jinja2" %}{% raw %}
-{% image "cat.jpg", "photo of my tabby cat" %}
-{% image "cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw" %}
-{% endraw %}{% endhighlight %}
-
The comma between arguments is required in Nunjucks templates.
-
-
- {% codetitle "JavaScript", "Syntax" %}
-{%- highlight "js" %}{% raw %}
-module.exports = function() {
- let img1 = await this.image("cat.jpg", "photo of my tabby cat");
- let img2 = await this.image("cat.jpg", "photo of my tabby cat", "(min-width: 30em) 50vw, 100vw");
-
- return `${img1}
-
-${img2}`;
-};
-{% endraw %}{% endhighlight %}
-
-
-
-
+{% include "snippets/image/templates.njk" %}
#### Synchronous Shortcode
@@ -381,10 +304,9 @@ ${img2}`;
Use `Image.statsSync` to get the metadata of a source even if the image generation is not finished yet:
-{% codetitle ".eleventy.js" %}
+{% set codeContent %}
+import Image from "@11ty/eleventy-img";
-```js
-const Image = require("@11ty/eleventy-img");
function imageShortcode(src, cls, alt, widths = ["auto"], sizes = "100vh") {
let options = {
widths,
@@ -406,10 +328,11 @@ function imageShortcode(src, cls, alt, widths = ["auto"], sizes = "100vh") {
return Image.generateHTML(metadata, imageAttributes);
}
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addShortcode("myImage", imageShortcode);
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -428,14 +351,11 @@ Using Eleventy Image in [WebC](/docs/languages/webc/) offers all the same great
First, add the following to your project’s configuration file:
-{% codetitle ".eleventy.js" %}
-
-```js
-const eleventyWebcPlugin = require("@11ty/eleventy-plugin-webc");
-const { eleventyImagePlugin } = require("@11ty/eleventy-img");
+{% set codeContent %}
+import eleventyWebcPlugin from "@11ty/eleventy-plugin-webc";
+import { eleventyImagePlugin } from "@11ty/eleventy-img";
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
// WebC
eleventyConfig.addPlugin(eleventyWebcPlugin, {
components: [
@@ -460,7 +380,8 @@ module.exports = function (eleventyConfig) {
},
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
{% addedin "v3.0.0-alpha.7" %}{% addedin "Image v5.0.0" %}During local development (when using `--serve`), `` images are _not_ processed at build time and instead are optimized when requested in the browser. Read more about [`transformOnRequest`](#optimize-images-on-request).
@@ -543,14 +464,11 @@ Image optimization is likely one of the costlier pieces of your Eleventy build.
{% addedin "v3.0.0-alpha.7" %}{% addedin "Image v5.0.0" %}You _can_ use this with the Eleventy Shortcode directly too, with a little bit more configuration:
-{% codetitle ".eleventy.js" %}
-
-```js
-const Image = require("@11ty/eleventy-img");
-const { eleventyImageOnRequestDuringServePlugin } = Image;
+{% set codeContent %}
+import Image from "@11ty/eleventy-img";
+import { eleventyImageOnRequestDuringServePlugin } from "@11ty/eleventy-img";
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addShortcode("image", async function (src, alt) {
let metadata = await Image(src, {
transformOnRequest: process.env.ELEVENTY_RUN_MODE === "serve"
@@ -563,7 +481,8 @@ module.exports = function (eleventyConfig) {
// Add the dev server middleware manually
eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -589,31 +508,27 @@ You can disable this behavior by using the `useCache` boolean option:
{% codetitle ".eleventy.js" %}
```js
-const Image = require("@11ty/eleventy-img");
+import Image from "@11ty/eleventy-img";
-(async () => {
- let stats1 = Image("./test/bio-2017.jpg");
- let stats2 = Image("./test/bio-2017.jpg");
+let stats1 = Image("./test/bio-2017.jpg");
+let stats2 = Image("./test/bio-2017.jpg");
- console.assert(stats1 === stats2, "The same promise");
-})();
+console.assert(stats1 === stats2, "The same promise");
```
Example of in-memory cache (returns a new promise with different options)
-{% codetitle ".eleventy.js" %}
+{% codetitle "eleventy.config.js" %}
```js
-const Image = require("@11ty/eleventy-img");
+import Image from "@11ty/eleventy-img";
-(async () => {
- let stats1 = Image("./test/bio-2017.jpg");
- let stats2 = Image("./test/bio-2017.jpg", { widths: [300] });
+let stats1 = Image("./test/bio-2017.jpg");
+let stats2 = Image("./test/bio-2017.jpg", { widths: [300] });
- console.assert(stats1 !== stats2, "A different promise");
-})();
+console.assert(stats1 !== stats2, "A different promise");
```
@@ -638,7 +553,7 @@ You can use this to [speed up builds on your build server](/docs/deployment/#per
Don’t like those hash ids? Make your own!
```js
-{
+ // (some configuration truncated…)
// Define custom filenames for generated images
filenameFormat: function (id, src, width, format, options) {
// id: hash of the original image
@@ -649,15 +564,14 @@ Don’t like those hash ids? Make your own!
return `${id}-${width}.${format}`;
}
-}
```
Custom Filename Example: Use the original file slug
```js
-const path = require("path");
-const Image = require("@11ty/eleventy-img");
+import path from "node:path";
+import Image from "@11ty/eleventy-img";
await Image("./test/bio-2017.jpg", {
widths: [300],
@@ -686,90 +600,7 @@ If you want to try the utility out and not write any files (useful for testing),
If you have an advanced use case and don’t want to use our methods to generate the image markup, you can do it yourself!
-
-
-
-
-{% codetitle ".eleventy.js" %}
-
-```js
-const Image = require("@11ty/eleventy-img");
-
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
- eleventyConfig.addShortcode("image", async function (src, alt) {
- if (alt === undefined) {
- // You bet we throw an error on missing alt (alt="" works okay)
- throw new Error(`Missing \`alt\` on myImage from: ${src}`);
- }
-
- let metadata = await Image(src, {
- widths: [600],
- formats: ["jpeg"],
- });
-
- let data = metadata.jpeg[metadata.jpeg.length - 1];
- return ``;
- });
-};
-```
-
-
-
-
-{% codetitle ".eleventy.js" %}
-
-```js
-const Image = require("@11ty/eleventy-img");
-
-// Only one module.exports per configuration file, please!
-module.exports = function (eleventyConfig) {
- eleventyConfig.addShortcode(
- "image",
- async function (src, alt, widths = [300, 600], sizes = "100vh") {
- if (alt === undefined) {
- // You bet we throw an error on missing alt (alt="" works okay)
- throw new Error(`Missing \`alt\` on responsiveimage from: ${src}`);
- }
-
- let metadata = await Image(src, {
- widths,
- formats: ["webp", "jpeg"],
- });
-
- let lowsrc = metadata.jpeg[0];
- let highsrc = metadata.jpeg[metadata.jpeg.length - 1];
-
- return `
- ${Object.values(metadata)
- .map((imageFormat) => {
- return ` `;
- })
- .join("\n")}
-
- `;
- }
- );
-};
-```
-
-
-
-
+{% include "snippets/image/diy.njk" %}
### Process images as a Custom Template
@@ -790,13 +621,11 @@ Use Eleventy’s [Custom Template Language](/docs/languages/custom/) feature to
Show the code
-{% codetitle ".eleventy.js" %}
-
-```js
-const Image = require("@11ty/eleventy-img");
-const path = require("path");
+{% set codeContent %}
+import path from "node:path";
+import Image from "@11ty/eleventy-img";
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addDataExtension("png,jpeg", {
read: false, // Don’t read the input file, argument is now a file path
parser: async (imagePath) => {
@@ -825,7 +654,8 @@ module.exports = function (eleventyConfig) {
return Image.generateHTML(stats, imageAttributes);
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
With a template `my-blog-post.md` and an image file `my-blog-post.jpeg`, you could use the above configuration code in your template like this:
@@ -850,7 +680,7 @@ Note this also means that `folder/folder.jpeg` would be processed for all templa
### Change Global Plugin Concurrency
```js
-const Image = require("@11ty/eleventy-img");
+import Image from "@11ty/eleventy-img";
Image.concurrency = 4; // default is 10
```
@@ -869,7 +699,7 @@ Image.concurrency = 4; // default is 10
{% addedin "Image v1.1.0" %} To process and output animated `gif` or `webp` images, use the `animated` option for the Sharp constructor.
```js
-const Image = require("@11ty/eleventy-img");
+import Image from "@11ty/eleventy-img";
await Image("./test/bio-2017.jpg", {
formats: ["webp", "gif"],
@@ -885,7 +715,7 @@ await Image("./test/bio-2017.jpg", {
{% addedin "1.0.0" %} You can customize the length of the default filename format hash by using the `hashLength` property.
```js
-const Image = require("@11ty/eleventy-img");
+import Image from "@11ty/eleventy-img";
await Image("./test/bio-2017.jpg", {
hashLength: 8, // careful, don’t make it _too_ short!
diff --git a/src/docs/plugins/render.md b/src/docs/plugins/render.md
index c67bd824e4..e577a98490 100644
--- a/src/docs/plugins/render.md
+++ b/src/docs/plugins/render.md
@@ -24,27 +24,24 @@ Everything you’ve added to project’s configuration file will also be availab
## 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.js`) with `addPlugin`:
+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`:
-{% codetitle ".eleventy.js" %}
+{% set codeContent %}
+import { EleventyRenderPlugin } from "@11ty/eleventy";
-```js
-const { EleventyRenderPlugin } = require("@11ty/eleventy");
-
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(EleventyRenderPlugin);
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
Expand to view all of the Plugin Options
-{% codetitle ".eleventy.js" %}
-
-```js
-const { EleventyRenderPlugin } = require("@11ty/eleventy");
+{% set codeContent %}
+import { EleventyRenderPlugin } from "@11ty/eleventy";
-module.exports = function (eleventyConfig) {
+export default function (eleventyConfig) {
eleventyConfig.addPlugin(EleventyRenderPlugin, {
tagName: "renderTemplate", // Change the renderTemplate shortcode name
tagNameFile: "renderFile", // Change the renderFile shortcode name
@@ -53,7 +50,8 @@ module.exports = function (eleventyConfig) {
accessGlobalData: false, // Does rendered content has access to the data cascade?
});
};
-```
+{% endset %}
+{% include "snippets/configDefinition.njk" %}
@@ -65,120 +63,13 @@ module.exports = function (eleventyConfig) {
Use the `renderTemplate` paired shortcode to render a template string.
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpl"} %}
-
-
-{% raw %}
-
-```liquid
-{% renderTemplate "md" %}
-# I am a title
-
-* I am a list
-* I am a list
-{% endrenderTemplate %}
-```
-
-{% endraw %}
-
-
-
-
-{% raw %}
-
-```jinja2
-{% renderTemplate "md" %}
-# I am a title
-
-* I am a list
-* I am a list
-{% endrenderTemplate %}
-```
-
-{% endraw %}
-
-
-
-
-{% raw %}
-
-```js
-module.exports = async function () {
- return await this.renderTemplate(
- `# I am a title
-
-* I am a list
-* I am a list`,
- "md"
- );
-};
-```
-
-{% endraw %}
-
-
-
-
+{% include "snippets/plugins/render.njk" %}
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`](/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, including [the Vue plugin](https://github.com/11ty/eleventy-plugin-vue)!
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmplvue"} %}
-
-
-{% raw %}
-
-```js
-module.exports = async function () {
- return await this.renderTemplate(
- `
- THIS IS VUE
-
`,
- "vue"
- );
-};
-```
-
-{% endraw %}
-
-
-
-
+{% 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 %}
@@ -188,63 +79,7 @@ To add Vue support, don’t forget to install [`@11ty/eleventy-plugin-vue` (v0.6
Both the [`eleventy`](/docs/data-eleventy-supplied/#eleventy-variable) and [`page` variables](/docs/data-eleventy-supplied/#page-variable) are available inside of these templates by default. If you want to pass in additional data, you can do so like this:
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "rendertmpldata"} %}
-
-
-
+{% include "snippets/plugins/renderfile.njk" %}
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](/docs/languages/custom/) you’ve added too, including a Vue Single File Component from the [Eleventy Vue plugin](https://github.com/11ty/eleventy-plugin-vue)!
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfilevue"} %}
-
-
-
+{% include "snippets/plugins/renderfilevue.njk" %}
To add Vue support, don’t forget to install [`@11ty/eleventy-plugin-vue` (v0.6.0 or newer)](https://github.com/11ty/eleventy-plugin-vue) and add the Vue plugin in your config file.
@@ -344,116 +101,12 @@ To add Vue support, don’t forget to install [`@11ty/eleventy-plugin-vue` (v0.6
Both the [`eleventy`](/docs/data-eleventy-supplied/#eleventy-variable) and [`page` variables](/docs/data-eleventy-supplied/#page-variable) are available inside of these templates by default. If you want to pass in additional data, you can do so like this:
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfiledata"} %}
-
-
-
+{% include "snippets/plugins/renderfiledata.njk" %}
#### 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`](/docs/languages/#templateengineoverride-examples) value. You can even use `"liquid,md"` to preprocess markdown with liquid.
-
-
- {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "renderfileoverride"} %}
-
`;
+ });
+};
+```
+
+
+