eleventy-plugin-vento 🌬️🎈🐀

An Eleventy plugin that adds support for Vento templates.

Contents

Installing Usage Plugin Options Filters Shortcodes (Single & Paired) Vento Plugins Auto-Trimming Tags Ignoring Tags

Installing

npm install eleventy-plugin-vento

Usage

This plugin is ESM only and cannot be required from CommonJS.

If you're using CommonJS and loading it asynchronously (ie await import), you will need at minimum Eleventy v3.0.0-alpha.15 which provides internal methods this plugin uses to get Eleventy stuff from the config API.

In your Eleventy config:

import { VentoPlugin } from 'eleventy-plugin-vento';

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(VentoPlugin);
}

Plugin Options

This plugin ships with default options out of the box, but you can pass an options object to your addPlugin call to configure things further. The below example shows the configurable options as well as their defaults.

import { VentoPlugin } from 'eleventy-plugin-vento';

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(VentoPlugin, {
    // An array of Vento plugins to use when compiling
    plugins: [],

    // Enable/disable Eleventy Shortcodes, Paired Shortcodes,
    // and Filters in .vto templates
    shortcodes: true,
    pairedShortcodes: true,
    filters: true,

    // Define tags that should be trimmed, or set to true
    // to trim the default tags (see section on Auto-trimming)
    autotrim: false,

    // Enable/disable ignore tag syntax (see section on ignoring tags)
    ignoreTag: false,

    // A Vento configuration object
    ventoOptions: {
      includes: eleventyConfig.directories.includes,
    },
  });
}

View the full list of options to pass as a Vento Configuration object (as ventoOptions).

Filters

[!NOTE] Remember, Vento can pipe any JS data type to any built-in global as the first-argument or any .prototype method in addition to declared filters. For instance to print the eleventy variable as JSON you could use the following snippet:

{{ eleventy |> JSON.stringify }}

In these cases, Eleventy filters may not be needed depending on your usage.

Filters that are added via Eleventy's .addFilter() or .addAsyncFilter() methods will be automatically loaded into Vento. Since Vento filters and Eleventy filters follow the same syntax for filters (content as first argument), the implementation is 1:1.

If you'd prefer to set filters yourself (via a plugin or other method) or prevent Eleventy from loading filters into Vento, set filters: false in the plugin options.

Relevant documentation

Vento: See Filters and Pipes

Eleventy: See Filters

Shortcodes (Single & Paired)

[!NOTE] Remember, Vento can print any return value from a Javascript expression, as well as run arbitrary JavaScript in templates through its {{> ...}} operator. In these cases, shortcodes may not be needed depending on your usage.

Single and Paired Shortcodes added via Eleventy's .addShortcode(), addAsyncShortcode(), addPairedShortcode() or .addAsyncPairedShortcode() will be automatically loaded into Vento.

When using shortcodes in your templates, write them like any other Vento tag:

{{ myShortcode }}

To pass arguments, add a space and your arguments, comma-separated. Arguments are interpreted as JavaScript so type-safety should be considered (quote strings, use booleans if your shortcode expects them, etc.)

{{ myShortcode 'arg1', 'arg2' }}
{{ myBooleanShortcode false, false, true }}
{{ myNumberShortcode 10, 20, 0 }}
{{ myObjectShortcode { key1: 'val1', key2: 'val2' } }}

For paired shortcodes, the syntax is the same, just add a closing tag. Paired shortcodes also accept arguments and can re-process nested Vento tags (including other shortcodes).

{{ codeBlock 'css' }} <!-- takes arguments too -->
  a {
    color: red;
  }
{{ /codeBlock }}

{{ blockQuote }}
  To be or not to be, that is the question.
  {{ attribute 'William Shakespeare' }} <!-- you can use vento syntax here too -->
{{ /blockQuote }}

If you'd prefer to set shortcodes yourself (via a plugin or other method) or prevent Eleventy from loading shortcodes into Vento, set shortcodes: false and/or pairedShortcodes: false in the plugin options.

[!CAUTION] While it's straightforward to load filters via a Vento plugin that appends filters to the filters object as env.filters.[filter_name](), creating custom tags in Vento is more involved. It's highly advised to keep these two options enabled unless you know what you're doing.

Relevant Documentation

Eleventy: See Shortcodes and the sub-section on Paired Shortcodes.

Vento Plugins

Note: The auto_trim plugin that ships with Vento has a specific implementation in the scope of this plugin. See Auto-Trimming Tags for more details.

If you'd like to extend the Vento library with any plugins, include them in an array passed to the plugins option.

import { VentoPlugin } from 'eleventy-plugin-vento';

function myCustomPlugin() {
  // ...plugin code...
}

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(VentoPlugin, {
    plugins: [myCustomPlugin],
  });
}

Auto-Trimming Tags

One exception to Vento plugins is the autoTrim plugin which is bundled with Vento, and by extension, this plugin. This plugin provides a convenient way to control whitespace in the output by collapsing spaces left behind when Vento's tags are removed.

To trim space around the default tags and all Eleventy paired shortcodes, set the autotrim plugin option to true.

eleventyConfig.addPlugin(VentoPlugin, {
  autotrim: true,
});

The default set of tags that are trimmed are defined by Vento itself. To set your own list of tags, set autotrim to an array of tags:

eleventyConfig.addPlugin(VentoPlugin, {
  autotrim: ['set', 'if', 'for'],
});

If instead, you'd like to extend instead of replace the default tag list, add the value @vento and/or @11ty. These placeholders will expand to the Vento default tags and Eleventy paired shortcode tags when the plugin executes.

import { VentoPlugin } from 'eleventy-plugin-vento';

eleventyConfig.addPlugin(VentoPlugin, {
  autotrim: {
    tags: ['@vento', '@11ty', 'tag'],
  },
});

Relevant documentation

Vento: See Auto Trim Plugin.

Ignoring Tags

Exclusive to this plugin is the ability to skip processing a vento tag entirely and instead preserve the tag in the markup. This could be useful if you're doing some hybrid rendering and would like to defer certain tags from being processed until load time, so they can be rendered on the server.

This feature is enabled through use of the enableIgnoreTag plugin option.

eleventyConfig.addPlugin(VentoPlugin, {
  enableIgnoreTag: true,
});

To skip over a tag, add a ! directly after the opening tag.

<!-- This: -->
{{! doSomeServerSideStuff() }}

<!-- Renders as: -->
{{ doSomeServerSideStuff() }}

Works with JS expressions too:

{{!> 2 + 2 }}

<!-- Renders as: -->
{{> 2 + 2 }}

The Vento language offers similar functionality via the echo tag which works great for blocks, but can be verbose for 1-off tags.

Consider the following:

{{ echo }}
  <!-- Will be preserved in output -->
  {{ if someCondition }}
    <p>{{ getServerData }}</p>
{{ /echo }}

    <!-- Can't render this without exiting and re-entering echo -->
    <p>Page built on: {{ localBuildTime }}</p>

{{ echo }}
  {{ /if }}
{{ /echo }}

Rather than having to do multiple {{ /echo }} ... {{ echo }} statements, the previous can be rewritten as such:

<!-- This: -->
{{! if someCondition }}
  <p>{{! getServerData }}</p>

  <p>Page built on: {{ localBuildTime }}</p>
{{! /if }}

<!-- Renders as: -->
{{ if someCondition }}
  <p>{{ getServerData }}</p>

  <p>Page built on: 09-19-2024</p>
{{ /if }}