eleventy-plugin-fluid
Advanced tools
Eleventy plugin which provides common filters, shortcodes and transforms for Fluid Project websites.
Eleventy plugin which provides common filters, shortcodes and transforms for Fluid Project websites.
Add eleventy-plugin-fluid to your Eleventy-based static site by running:
npx install-peerdeps eleventy-plugin-fluid
(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.config.js), load the plugin as follows:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
config.addPlugin(fluidPlugin);
};
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:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ "override:css": {
+ // Your options here.
+ }
+ });
};
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.
eleventy-plugin-fluid includes configuration for processing and bundling Sass and CSS files using Sass
and LightningCSS, and JavaScript files using esbuild.
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:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ css: {
+ cssModules: true,
+ }
+ });
};
Default values are as follows:
let options = {
/* Where should Eleventy look for CSS files to process? */
basePath: `./${eleventyConfig.dir.input || "src"}/assets/styles`,
/* Should CSS files be processed? */
enabled: true,
/* See: https://lightningcss.dev/minification.html */
minify: true,
/* Not yet supported, see https://github.com/fluid-project/eleventy-plugin-fluid/issues/170 */
sourceMap: false,
/* See: https://lightningcss.dev/transpilation.html#draft-syntax */
drafts: {
nesting: true
},
/* A Browserslist configuration string (see: https://browsersl.ist) */
browserslist: "> 1%"
};
If you wish to disable CSS processing altogether, set the enabled key of the options.css object to false.
If you wish to disable Browserslist altogether, you can pass an empty array ([]) to the browserslist key.
For more options, see the LightningCSS docs.
Sass processing is disabled by default. When enabled, any Sass files with the .scss extension found in the
./src/assets/styles/ directory or its children will be processed unless the filename begins with an underscore (_).
To enable Sass and disable CSS, add the following configuration when registering eleventy-plugin-fluid in your config:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ css: {
+ enabled: false
+ },
+ sass: {
+ enabled: true
+ }
+ });
};
Options for Sass may be modified by passing values to the sass option when registering eleventy-plugin-fluid
in your config:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ css: {
+ enabled: false
+ },
+ sass: {
+ browserslist: '> 1.5%',
+ enabled: true
+ }
+ });
};
Default values are as follows:
let options = {
/* Where should Eleventy look for Sass files to process? */
basePath: `./${eleventyConfig.dir.input || "src"}/assets/styles`,
/* Should Sass files be processed? */
enabled: false,
/* See: https://lightningcss.dev/minification.html */
minify: true,
/* Not yet supported, see https://github.com/fluid-project/eleventy-plugin-fluid/issues/170 */
sourceMap: false,
/* See: https://lightningcss.dev/transpilation.html#draft-syntax */
drafts: {
nesting: true
},
/* A Browserslist configuration string (see: https://browsersl.ist) */
browserslist: "> 1%"
};
Note that all of these will be passed to LightningCSS, not Sass, with the exception of basePath, enabled, and sourceMap.
If you wish to disable Sass processing altogether, set the enabled key of the options.sass object to false.
If you wish to disable Browserslist altogether, you can pass an empty array ([]) to the browserslist key.
For more options, see the Sass and LightningCSS docs.
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:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ js: {
+ target: "esnext"
+ }
+ });
};
Default values are as follows:
let 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: "es2020",
basePath: `./${eleventyConfig.dir.output || "_site"}/assets/styles`
};
If you wish to disable JavaScript processing altogether, set the enabled key of the options.js object to false.
eleventy-plugin-fluid adds support for localization using Eleventy's i18n plugin
and eleventy-plugin-i18n-gettext for string translation.
By default, the following languages are configured:
enen-CAen-USesfafrpt-brYou can add support for additional languages by passing values to the supportedLanguages option when registering
eleventy-plugin-fluid in your config:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.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:
{
"defaultLanguage": "en",
"defaultLanguageDir": "ltr",
"supportedLanguages": {
"en": {
"slug": "en",
"uioSlug": "en",
"dir": "ltr",
"name": "English"
},
"en-CA": {
"slug": "en-ca",
"uioSlug": "en_CA",
"dir": "ltr",
"name": "English (Canada)"
},
"en-US": {
"slug": "en-us",
"uioSlug": "en_US",
"dir": "ltr",
"name": "English (United States)"
},
"es": {
"slug": "es",
"uioSlug": "es",
"dir": "ltr",
"name": "Español"
},
"fa": {
"slug": "fa",
"uioSlug": "fa",
"dir": "rtl",
"name": "فارسی"
},
"fr": {
"slug": "fr",
"uioSlug": "fr",
"dir": "ltr",
"name": "Français"
},
"pt-BR": {
"slug": "pt-br",
"uioSlug": "pt_BR",
"dir": "ltr",
"name": "Português (Brasil)"
}
}
}
The defaultLanguage can be overridden by passing a new value to the defaultLanguage options key when registering
eleventy-plugin-fluid.
By default, eleventy-plugin-fluid also configures a localesDirectory
for eleventy-plugin-i18n-getttext as ./src/_locales. This can be overridden by passing a new value to the
localesDirectory options key when registering eleventy-plugin-fluid.
eleventy-plugin-fluid also provides two localization-related helpers:
generatePermalinkgeneratePermalink 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:
const { EleventyI18nPlugin } = require("@11ty/eleventy");
const { generatePermalink } = require("eleventy-plugin-fluid");
const { _ } = require("eleventy-plugin-i18n-gettext");
module.exports = {
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 => {
const locale = data.locale;
return generatePermalink(data, "pages", _(locale, "pages"), _(locale, "page"));
}
}
};
In this example, eleventy-plugin-i18n-gettext is used
to localize the URL path for the collection. The _() method provided by eleventy-plugin-i18n-gettext requires a
variable called locale as its first parameter (see this issue).
localizeDatalocalizeData is used to localize directory data
for a directory of content in a specific language (where the directory name is the language code). Here's an example,
as used in an 11tydata.js file:
const { localizeData } = require("eleventy-plugin-fluid");
module.exports = () => {
return localizeData({}, __dirname);
};
This helper is a wrapper for i18n.enhance11tydata.
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:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ i18n: false
+ });
};
Note that if you do this, you will need to remove any uses of the localizeData helper or
eleventy-plugin-i18n-gettext functions in your
project.
For additional information on setting up localization/internationalization, see:
eleventy-plugin-fluid amends Eleventy's default Markdown configuration
as follows (for more information see markdown-it):
{
"html": true,
"linkify": true,
"typographer": true
}
Options for Markdown may be modified by passing values to the markdown option when registering eleventy-plugin-fluid
in your config:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ markdown: {
+ options: {
+ breaks: "true"
+ }
+ }
+ });
};
You can also enable markdown-it plugins when
registering eleventy-plugin-fluid as follows:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ markdown: {
+ plugins: [
+ // The npm package name of the plugin, which must be installed in your project.
+ "markdown-it-emoji",
+ // The npm package name of the plugin, which must be installed in your project, and an options object for the plugin.
+ ["markdown-it-anchor", {}]
+ ]
+ }
+ });
};
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.
Formats a date string.
{{ "Sun Jun 21 2020 18:00:00 GMT-0300 (Atlantic Daylight Time)" | formatDate }}
Output: June 21st, 2020
Optionally, a locale parameter
can be supplied to format a date in a locale other than English.
{{ "Sun Jun 21 2020 18:00:00 GMT-0300 (Atlantic Daylight Time)" | formatDate('fr') }}
Output: 21 juin 2020
Formats a date string to ISO 8601 format.
{{ "Sun Jun 21 2020 18:00:00 GMT-0300 (Atlantic Daylight Time)") | isoDate }}
Output: 2020-06-21T21:00:00.000Z
Trims an array to the specified length.
{{ ["a", "b", "c"] | limit(2) | dump }}
Output: ["a", "b"]
Processes an input string using Markdown.
{{ "A paragraph with some _emphasis_." | markdown | safe }}
Output: <p>A paragraph with some <em>emphasis</em>.</p>\n
Processes an input string by lowercasing it, replacing whitespace with hyphens, and stripping special characters to create a URL-safe version.
NOTE: This filter is deprecated and the slug-filter.js file has been removed as of eleventy-plugin-fluid 1.0.
Instead, use Eleventy's new slugify filter.
Splits an input string into an array based on a provided delimiter.
{{ "a,b,c" | split(",") | dump }}
Output: ["a", "b", "c"]
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.
Outputs a <figure> element with a <figcaption>. 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.
{% figure "/assets/image.png", "A description of this image." %}
An illustration of something, found [here](https://example.com).
{% endfigure %}
Output:
<figure>
<img src="/assets/image.png" alt="A description of this image." />
<figcaption>
<p>An illustration of something, found <a href="https://example.com">here</a>.</p>
</figcaption>
</figure>
Renders a string with a supported template engine using the Eleventy Render plugin. This can be particularly useful when front matter data from a template needs to be processed using Markdown.
---
title: About
subtitle: Learn about our [mission](/about/mission/), [vision](/about/vision/), and [values](/about/values/).
---
This is what we do.
<h1>{{ title }}</h1>
<div class="subtitle">
{% renderString subtitle, "md" %}
</div>
{{ content | safe }}
Result:
<h1>About</h1>
<div class="subtitle">
<p>Learn about our <a href="/about/mission/">mission</a>, <a href="/about/vision/">vision</a>, and <a href="/about/values/">values</a>.</p>
</div>
<p>This is what we do.</p>
By default, the following template formats are supported:
html)md)webc)11ty.js)liquid)njk)hbs)mustache)ejs)haml)pug)For example, you could enable Vue support when registering
eleventy-plugin-fluid as follows:
const fluidPlugin = require("eleventy-plugin-fluid");
+ const eleventyVue = require("@11ty/eleventy-plugin-vue");
module.exports = function (config) {
+ config.addPlugin(eleventyVue);
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ templateFormats: [
+ "vue"
+ ]
+ });
};
Outputs links to the required CSS assets for an instance of Infusion User Interface Options. 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.
{% uioStyles %}
Result:
<link href="/lib/infusion/src/framework/core/css/fluid.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/Enactors.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/PrefsEditor.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/SeparatedPanelPrefsEditor.css" rel="stylesheet">
Outputs links to the required CSS assets for an instance of Infusion User Interface Options. This only includes the related CSS Custom Properties. Use this when you want to have control over how the enactor styles are applied.
See: Integrating UI Options Styling Preferences
{% uioStyleProps %}
Result:
<link href="/lib/infusion/src/framework/core/css/fluid.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/Contrast_base.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/EnhanceInputs_base.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/Font_base.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/PrefsEditor.css" rel="stylesheet">
<link href="/lib/infusion/src/framework/preferences/css/SeparatedPanelPrefsEditor.css" rel="stylesheet">
Outputs links to the required JavaScript assets for an instance of Infusion User Interface Options.
{% uioScripts %}
Result:
<link rel="preload" href="/lib/infusion/infusion-uio.js" as="script" />
<script src="/lib/infusion/infusion-uio.js"></script>
Outputs the required HTML template markup for an instance of Infusion User Interface Options. This should used
directly after the opening <body> tag.
{% uioTemplate %}
Result:
<div class="flc-prefsEditor-separatedPanel fl-prefsEditor-separatedPanel">
<div class="fl-panelBar fl-panelBar-smallScreen" id="Editorspace">
<span class="fl-prefsEditor-buttons">
<button class="flc-slidingPanel-toggleButton fl-prefsEditor-showHide"> Show/Hide</button>
<button class="flc-prefsEditor-reset fl-prefsEditor-reset"><span class="fl-icon-undo"></span> Reset</button>
</span>
</div>
<div class="flc-slidingPanel-panel"></div>
<div class="fl-panelBar fl-panelBar-wideScreen">
<span class="fl-prefsEditor-buttons">
<button class="flc-slidingPanel-toggleButton fl-prefsEditor-showHide"> Show/Hide</button>
<button class="flc-prefsEditor-reset fl-prefsEditor-reset"><span class="fl-icon-undo"></span> Reset</button>
</span>
</div>
</div>
If you want to use a custom integration of User Interface Options, you can insert the required markup directly into your base template.
Outputs the required JavaScript to initialize an instance of Infusion User Interface Options. This should used
directly before the closing </body> tag.
{% uioInit %}
Result:
<script>
fluid.uiOptions.multilingual(".flc-prefsEditor-separatedPanel", {
"auxiliarySchema": {
"terms": {
"templatePrefix": "/lib/infusion/src/framework/preferences/html",
"messagePrefix": "/lib/infusion/src/framework/preferences/messages"
},
"fluid.prefs.tableOfContents": {
"enactor": {
"tocTemplate": "/lib/infusion/src/components/tableOfContents/html/TableOfContents.html",
"tocMessage": "/lib/infusion/src/framework/preferences/messages/tableOfContents-enactor.json",
"ignoreForToC": {
"ignoreClass": ".flc-toc-ignore"
}
}
}
},
"prefsEditorLoader": {
"lazyLoad": true
}
});
</script>
Optionally, to support localization, you can pass in locale and direction arguments.
{% uioInit "fa", "rtl" %}
Result:
<script>
fluid.uiOptions.multilingual(".flc-prefsEditor-separatedPanel", {
"auxiliarySchema": {
"terms": {
"templatePrefix": "/lib/infusion/src/framework/preferences/html",
"messagePrefix": "/lib/infusion/src/framework/preferences/messages"
},
"fluid.prefs.tableOfContents": {
"enactor": {
"tocTemplate": "/lib/infusion/src/components/tableOfContents/html/TableOfContents.html",
"tocMessage": "/lib/infusion/src/framework/preferences/messages/tableOfContents-enactor.json",
"ignoreForToC": {
"ignoreClass": ".flc-toc-ignore"
}
}
}
},
"prefsEditorLoader": {
"lazyLoad": true
},
"locale": "fa",
"direction": "rtl"
});
</script>
If you want to use a custom integration of User Interface Options, you can insert the required script tag directly into your base template.
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:
const fluidPlugin = require("eleventy-plugin-fluid");
module.exports = function (config) {
- config.addPlugin(fluidPlugin);
+ config.addPlugin(fluidPlugin, {
+ webc: {
+ components: "./src/_includes/**/*.webc"
+ }
+ });
};
eleventy-plugin-fluid adds an HTML minify transform to output files with a .html extension which minifies them
using html-minifier.
By default, eleventy-plugin-fluid copies the required assets for an instance of
Infusion User Interface Options into the lib/infusion directory of the build directory.
This package uses Conventional Commits, enforced with commitlint. This facilitates releasing new versions of the package via Release Please. To cut a release, merge the current release pull request.
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:
npm publish
For more information on publishing to npm, see the npm publish documentation.
eleventy-plugin-fluideleventy-plugin-fluid is based on other publicly available software, categorized by license:
FAQs
Eleventy plugin which provides common filters, shortcodes and transforms for Fluid Project websites.
We found that eleventy-plugin-fluid demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.