(You can also run npm install --save eleventy-plugin-fluid, but you'll then need to install the specified infusion peer dependency in your project as well; the install-peerdeps command handles both at the same time.)
Then, in your Eleventy configuration file (usually eleventy.eleventyConfig.js), load the plugin as follows:
`js import fluidPlugin from 'eleventy-plugin-fluid';
/** * @param {object} eleventyConfig The Eleventy configuration object. */ export default function eleventy(eleventyConfig) { eleventyConfig.addPlugin(fluidPlugin); } `
Usage
For any options passed to eleventy-plugin-fluid in the configurations described below, you can override the default rather than merging with it by passing the option with override: as a prefix to the key. For example, to override the default options for the css configuration block, you could do the following:
`diff import fluidPlugin from "eleventy-plugin-fluid";
Note that if you don't override required defaults when using this method, your configuration will not be valid, so proceed with caution if you are using this technique.
$3
eleventy-plugin-fluid includes configuration for processing and bundling CSS files using LightningCSS, and JavaScript files using esbuild.
#### CSS
By default, any CSS files found in the ./src/assets/styles/ directory or its children will be processed _unless the filename begins with an underscore (_)_. For this reason, if you are using CSS partials via the @import rule, you should name them according to the pattern _partial.css to prevent them from being transformed as standalone files (this convention will be familiar to those who have worked with Sass and Sass partials).
Options for LightningCSS may be modified by passing values to the css option when registering eleventy-plugin-fluid in your config:
`diff import fluidPlugin from "eleventy-plugin-fluid";
By default, any JavaScript files with the .js extension found in the ./src/assets/scripts/ directory or its children will be processed with esbuild _unless the filename begins with an underscore (_)_.
Options for esbuild may be modified by passing values to the js option when registering eleventy-plugin-fluid in your config:
`diff import fluidPlugin from "eleventy-plugin-fluid";
`js / global eleventyConfig / / eslint-disable no-unused-vars / const options = { / Where should Eleventy look for JavaScript files to process? / basePath: ./${eleventyConfig.dir.input || 'src'}/assets/scripts, / Should JavaScript files be processed? / enabled: true, / See: https://esbuild.github.io/api/#minify / minify: true, / See: https://esbuild.github.io/content-types/#javascript / target: 'es2022', }; `
If you wish to disable JavaScript processing altogether, set the enabled key of the options.js object to false.
$3
eleventy-plugin-fluid adds support for localization using Eleventy's i18n plugin and i18n-js for string translation.
By default, the following languages are configured:
- en - en-CA - en-US - es - fa - fr - pt-br
You can add support for additional languages by passing values to the supportedLanguages option when registering eleventy-plugin-fluid in your config:
`diff import fluidPlugin from "eleventy-plugin-fluid";
export default function (eleventyConfig) { - eleventyConfig.addPlugin(fluidPlugin); + eleventyConfig.addPlugin(fluidPlugin, { + supportedLanguages: { + de: { + // The slug which will be used in URLs to content in this language. + slug: "de", + // The slug which will be used to localize UIO (see: https://docs.fluidproject.org/infusion/development/localizationinthepreferencesframework#specifying-a-localization) + uioSlug: "de", + // The direction of the language. + dir: "ltr", + // The endonym of the language. + name: "Deutsch" + } + } + }); }; `
eleventy-plugin-fluid provides the following global data:
All content—collections or individual pages—must have a lang data value corresponding to a configured language. This will be automatically populated by the Eleventy internationalization plugin based on the page's inputPath or configured permalink, falling back the configured defaultLanguage.
#### Helper Functions
eleventy-plugin-fluid also provides four localization-related helpers:
##### __
__ is used to translate a string, substituting values for placeholders where required. For example:
The first parameter is the key for the translation string in the translations object, the second parameter is an object of values to substitute for placeholders in the translation string, and the third parameter is the data object containing the lang and translations values. If the third parameter is not provided, the function will try to retrieve these values from this.ctx which provides access to Eleventy's global data.
eleventy-plugin-fluid also provides a shortcode based on this function:
Nunjucks
`nunjucks {% __ 'hello', {name: 'world'} %} `
11ty.js
`js / eslint-disable unicorn/no-anonymous-default-export / /** * @param {string} key - The translation key. Must exist in (at least) one language within the translations object. * @param {object} values - An object containing values which can be substituted for keyed placeholders in the translated string. * @returns {string} - The localized string. */ export default function (key, values) { return this.__(key, values); } `
Note: Using this function with Liquid requires extra work as Liquid shortcodes cannot accept a JSON object directly.
##### generatePermalink
generatePermalink is used to generate localized permalinks for a collection type, with full support for pagination. Here's an example, as used in an 11tydata.js file:
`js import {EleventyI18nPlugin} from '@11ty/eleventy'; import {generatePermalink, __} from 'eleventy-plugin-fluid';
export default { layout: 'layouts/base.njk', eleventyComputed: { lang: data => EleventyI18nPlugin.LangUtils.getLanguageCodeFromInputPath(data.page.inputPath), langDir: data => data.supportedLanguages[data.lang].dir, locale: data => data.lang, permalink(data) { // Only localize the permalink if the locale or translations global data are present. if (Object.hasOwn(data, 'lang') || Object.hasOwn(data, 'translations')) { return generatePermalink(data, 'pages', __('pages', {}, data), __('pages', {}, data)); }
In this example, the __ function is used to localize the URL path for the collection.
##### languageDirection
The languageDirection filter can be used to determin the language direction (ltr or rtl) for an input language:
Nunjucks
`nunjucks
`
#### Disabling String Translation
If you don't need string translation features in your project, you can disable string translation by setting the i18n option to false when registering eleventy-plugin-fluid in your config:
`diff import fluidPlugin from "eleventy-plugin-fluid";
You can also enable markdown-it plugins when registering eleventy-plugin-fluid as follows:
`diff import fluidPlugin from "eleventy-plugin-fluid"; + import markdownItDefList from "markdown-it-deflist"; + import markdownItEmoji from "markdown-it-emoji";
export default function (eleventyConfig) { - eleventyConfig.addPlugin(fluidPlugin); + eleventyConfig.addPlugin(fluidPlugin, { + markdown: { + plugins: [ + // The imported plugin. + markdownItDefList, + // The imported plugin and an options object for the plugin. + [markdownItEmoji, {}] + ] + } + }); }; `
$3
All examples use the Nunjucks template language. Eleventy supports a number of other template languages; see Eleventy's documentation on filters for usage with different template languages.
#### find
Given an array of objects, this finds the first object where the specified property matches the given value. If the property is an array, it checks whether the array contains the value. Useful for finding an item in a collection.
Given a collection item, a collection object, the current language and the desired language, this filter will return the URL of the matching collection item in the desired language.
For example, if there is a posts collection with content and English and French, you can use this filter to create a link to the post in the other language as follows:
`nunjucks {{ "A paragraph with some _emphasis_." | markdown | safe }} `
Output:
A paragraph with some emphasis.
\n
#### slug (deprecated)
Processes an input string by lowercasing it, replacing whitespace with hyphens, and stripping special characters to create a URL-safe version.
**NOTE: This filter has been completely removed as of eleventy-plugin-fluid 3.0. Instead, use Eleventy's
slugify filter.**
#### split
Splits an input string into an array based on a provided delimiter.
`nunjucks {{ "a,b,c" | split(",") | dump }} `
Output:
["a", "b", "c"]
$3
All examples use the Nunjucks template language. Eleventy supports a number of other template languages; see Eleventy's documentation on shortcodes for usage with different template languages.
#### figure
Outputs a
element with a . The first and second parameters in the opening tag of the shortcode are the image URL and alternative text respectively. Caption content, which can use Markdown, goes in between the opening and closing shortcode tags.`nunjucks {% figure "/assets/image.png", "A description of this image." %} An illustration of something, found here. {% endfigure %} `
Outputs links to the required CSS assets for an instance of [Infusion User Interface Options][1]. Use this when you want the out-of-the-box/drop-in experience with UI Options styles overriding the site styles. This is the quickest way to start, but harder to customize and fit with your site's own styling.
`nunjucks {% uioStyles %} `
Result:
`html
`
#### uioStyleProps
Outputs links to the required CSS assets for an instance of [Infusion User Interface Options][1]. This only includes the related CSS Custom Properties. Use this when you want to have control over how the enactor styles are applied.
Outputs links to the required JavaScript assets for an instance of [Infusion User Interface Options][1].
`nunjucks {% uioScripts %} `
Result:
`html
`
#### uioTemplate
Outputs the required HTML template markup for an instance of [Infusion User Interface Options][1]. This should used directly after the opening
tag.`nunjucks {% uioTemplate %} `
Result:
`html
`
If you want to use a custom integration of User Interface Options, you can insert the required markup directly into your base template.
#### uioInit
Outputs the required JavaScript to initialize an instance of [Infusion User Interface Options][1]. This should used directly before the closing
tag.`nunjucks {% uioInit %} `
Result:
`html
`
Optionally, to support localization, you can pass in locale and direction arguments.
`nunjucks {% uioInit "fa", "rtl" %} `
Result:
`html
`
If you want to use a custom integration of User Interface Options, you can insert the required script tag directly into your base template.
$3
#### WebC
eleventy-plugin-fluid adds the Eleventy WebC plugin for WebC support. By default, the plugin will look for WebC components in ./src/_components/*/.webc. This, and other options, can be modified when registering eleventy-plugin-fluid:`diff import fluidPlugin from "eleventy-plugin-fluid";
eleventy-plugin-fluid adds an HTML minify transform to output files with a .html extension which minifies them using html-minifier.
Passthrough Copy
By default,
eleventy-plugin-fluid copies the required assets for an instance of [Infusion User Interface Options][1] into the lib/infusion directory of the build directory.
eleventy-plugin-fluid v3.x requires Eleventy v3.x and is written in ESM. See this post for upgrade information and guidance. - BREAKING: The markdown filter has been removed. Please use the Eleventy Render plugin's renderContent filter instead.
This will tag an appropriate semantic version based on the nature of the recent commits to the project and update the changelog.
You will then need to publish the updated version to the npm registry. This requires an npm account with appropriate maintainer permissions. To publish the package, run:
