eleventy-plugin-vento 2.6.0 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,235 @@
+# eleventy-plugin-vento
+
+## 3.0.1
+
+### Patch Changes
+
+- 9f5a90f: Various Refactors - These changes shouldn't have any observable effect on your templates or usage.
+
+  - Replaced `class` based approach for a closure implementation instead. Since there was only 1 Vento `env` object ever instanced in this plugin, steering away from using `class` removes some complexity and overhead.
+
+  - `DATA_KEYS` (used internally) moved into utils file alongside other utilities (like compatibility checks) and renamed to `CONTEXT_DATA_KEYS`.
+
+  - Moved internal Vento/11ty data from env.\_11ty => env.utils.\_11ty. Previous versions mutated the Vento `env` object by adding an `_11ty` key with everything that needed accessing from within a template compile (shortcodes, filters, etc.). This was moved this back to `env.utils._11ty` since it's probably a more appropriate place to store these functions.
+
+## 3.0.0
+
+### Major Changes
+
+- 668700c: Enforce new minimum version — [Eleventy v3.0.0-alpha.15](https://github.com/11ty/eleventy/releases/tag/v3.0.0-alpha.15) or later is now **required** for this plugin to function.
+
+  Although this goes against the _backwards compatibility_ ethos of Eleventy, the addition of the `getShortcodes()` and `getPairedShortcodes()` functions that were added in `alpha.15` are now utilized in this plugin to bring even more goodness to your templates.
+
+  Thanks [@zachleat](https://github.com/zachleat) for making this possible!
+
+- 9d8eb8a: Adds complete support for Eleventy shortcodes and filters within Vento. Shortcodes are now loaded by default as Vento tags and will no longer be exposed as functions in your page data.
+
+  The implementation of single shortcodes remains largely similar, just replace function-like calls with Vento tags.
+
+  ```diff
+  - {{ nametag('Noel', 'Forte') }}
+  + {{ nametag 'Noel', 'Forte' }}
+  ```
+
+  Of course, the big news is that **paired** shortcodes are now officially supported by this plugin!! Prior to this release, paired shortcodes were exposed just like regular shortcodes, but were plain JS functions. With this release you can now use paired shortcodes just like any other tag.
+
+  ```hbs
+  <!-- Before: everything is jammed into the function call :( -->
+  {{ blockquote("<p>Call me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</p>\n<p>It is a way I have of driving off the spleen and regulating the circulation.</p>", "Herman Melville", "1851") }}
+
+  <!-- After: opening and closing tags with arguments separated :) -->
+  {{ blockquote 'Herman Melville', '1851' }}
+    <p>Call me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</p>
+    <p>It is a way I have of driving off the spleen and regulating the circulation.</p>
+  {{ /blockquote }}
+  ```
+
+  Because these changes removed direct dependence on Eleventy JavaScript functions, the `addHelpers` option has been replaced with 3 new options: `shortcodes`, `pairedShortcodes` and `filters`. **All of them are enabled by default** but can be disabled in your plugin config like so.
+
+  ```diff
+  eleventyConfig.addPlugin(VentoPlugin, {
+  - addHelpers: false,
+  + shortcodes: false,
+  + pairedShortcodes: false,
+  + filters: false,
+  });
+  ```
+
+- 516cd2f: Modifications to `auto_trim` functionality
+
+  Starting with this release the way the `auto_trim` plugin is implemented is a bit different.
+
+  The plugin option `trimTags` is now `autotrim`. Be sure to update your plugin options object accordingly:
+
+  ```diff
+  eleventyConfig.addPlugin(VentoPlugin, {
+  - trimTags: true
+  + autotrim: true
+  });
+  ```
+
+  Additionally, the eleventy plugin no longer re-exports `defaultTags` from `ventojs`. Be sure to remove any imports from your config:
+
+  ```diff
+  - import { ventoDefaultTrimTags } from 'eleventy-plugin-vento';
+  ```
+
+  To extend the default tags list, this plugin now provides a 2 placeholder values for your array of tags, `@vento` and `@11ty`. When the plugin executes, `@vento` will be expanded to the default vento tags list, and `@11ty` will be expanded to the names of all paired shortcodes.
+
+  ```js
+  eleventyConfig.addPlugin(VentoPlugin, {
+    autotrim: ['@vento', '@11ty', 'tag1', 'tag2'],
+  });
+  ```
+
+  Setting `autotrim: true` is the same as `autotrim: ['@vento', '@11ty']`.
+
+### Minor Changes
+
+- ff75e09: Add option to explicitly enable tag ignore syntax.
+
+  Prior to this release this feature was referred to as the "SSR" or "hybrid-rendering" syntax. It's purpose was to skip over processing a tag like Vento's built-in `{{ echo }}` tag, but with a much shorter syntax: `{{! ... }}`. Any code following a `!` in your markup is wrapped in `{{ }}` and output as-is.
+
+  ```hbs
+  {{!> console.log('Hello world'); }} <!-- tag remains in output -->
+  ```
+
+  In this release, this behavior is now explicitly opt-in. To enable it, include `ignoreTag: true` in the plugin options:
+
+  ```js
+  eleventyConfig.addPlugin(VentoPlugin, {
+    ignoreTag: true,
+  });
+  ```
+
+- b9e8232: Update ventojs to 1.12.10
+
+## 2.6.0
+
+### New Features
+
+- fine-tune caching ([5b5035a](https://github.com/noelforte/eleventy-plugin-vento/commit/5b5035aedd89f57cb7d06e23d6fdef26fde55644))
+
+### Bug Fixes
+
+- remove `inputPath` from cache if `rawInput` doesn't match `inputContent` ([529d0b5](https://github.com/noelforte/eleventy-plugin-vento/commit/529d0b56fcc9175c698c7f243db51f79088d0849))
+
+## 2.5.0
+
+### Dependency Updates
+
+- update dependency ventojs to v0.12.9 ([2f664f3](https://github.com/noelforte/eleventy-plugin-vento/commit/2f664f39fac591b5daf9154b2c639542a65d9aad))
+
+## 2.4.0
+
+### Dependency Updates
+
+- update dependency ventojs to v0.12.8 ([f08ed15](https://github.com/noelforte/eleventy-plugin-vento/commit/f08ed15e42b67a044ac171156d6bf768e6bed7e5))
+
+## 2.3.0
+
+### New Features
+
+- `!` tag ([49bdaf8](https://github.com/noelforte/eleventy-plugin-vento/commit/49bdaf8a0ac65a3bab6d7de5abcba7c20ee3fcaf))
+
+## 2.2.0
+
+### New Features
+
+- update ventojs to 0.12.7 ([f4735ba](https://github.com/noelforte/eleventy-plugin-vento/commit/f4735bacdeae3605cdc0ba4e8b9bc9ec2f84d30d))
+
+### Bug Fixes
+
+- remove input path when compiling permalinks, it messes up the cache ([7dcae1a](https://github.com/noelforte/eleventy-plugin-vento/commit/7dcae1a7eb4b8611d5df982e42f6abe9b69f2871))
+
+## 2.1.0
+
+### New Features
+
+- only bind `page` and `eleventy` to helper functions to align with core functionality ([a2e023c](https://github.com/noelforte/eleventy-plugin-vento/commit/a2e023cab00666046f99dc99857a77514be4622d))
+
+### Bug Fixes
+
+- `trimTags` now applies default tags as expected when set to `true` ([9b25279](https://github.com/noelforte/eleventy-plugin-vento/commit/9b252796f3bb31963a5435bc0cc1e238392c74e1))
+- **filters:** use env.filters instead of filters so filters load correctly ([145029e](https://github.com/noelforte/eleventy-plugin-vento/commit/145029efc3b421b04189b665740825b4f32eff2c))
+- use `eleventyConfig.directories` to resolve `includes` directory ([3e1a88a](https://github.com/noelforte/eleventy-plugin-vento/commit/3e1a88a0e651033e7bba35431bcb0ce8d16a9cd7))
+
+## 2.0.0
+
+### ⚠ BREAKING CHANGES
+
+- rework filters to pull from eleventy definitions rather than defining a separate object
+
+### New Features
+
+- compile permalinks with vento using instance configuration ([170dc4d](https://github.com/noelforte/eleventy-plugin-vento/commit/170dc4d5a45f8a3dd25f57b99cfea9db8196a820))
+- rework filters to pull from eleventy definitions rather than defining a separate object ([a98355a](https://github.com/noelforte/eleventy-plugin-vento/commit/a98355a8a0fcdc8f63ba507997f1a5e93b0b266a))
+- wire up internal autoTrim plugin as trimTags option ([7756c06](https://github.com/noelforte/eleventy-plugin-vento/commit/7756c06f02ccbab5a689909e66733d09d1ab2c19))
+
+### Bug Fixes
+
+- add exports to package.json ([b07c53b](https://github.com/noelforte/eleventy-plugin-vento/commit/b07c53bc6a804608ad7a395a1f1e8d540ebaded8))
+- exports from VentoPlugin and imports/syntax on eleventy.config.js ([f719c99](https://github.com/noelforte/eleventy-plugin-vento/commit/f719c990580241c343e7e2c0753926a6086d4e32))
+- only compile linkContents if it's a string ([ddca393](https://github.com/noelforte/eleventy-plugin-vento/commit/ddca393d837c175e8f3707cea9e1eb863bd10ec3))
+- set up filters beforehand so they're accessible in permalinks ([58a4992](https://github.com/noelforte/eleventy-plugin-vento/commit/58a4992ea56778d8da28869c3ae06a499243cf90))
+
+## 2.0.0-beta.5
+
+### Bug Fixes
+
+- compile permalinks properly so permalinks starting with `/` don't default to their `permalink` values ([fc69db5](https://github.com/noelforte/eleventy-plugin-vento/commit/fc69db5b60acb0ba1a0aa5247ad71ace6610c3b7))
+- move cache clearing to compile step, rather than eleventy.before. ([44a424c](https://github.com/noelforte/eleventy-plugin-vento/commit/44a424cf0b10b641f67aadba0670f112e6e0d06c))
+
+## 2.0.0-beta.4
+
+### Bug Fixes
+
+- only compile linkContents if it's a string ([ddca393](https://github.com/noelforte/eleventy-plugin-vento/commit/ddca393d837c175e8f3707cea9e1eb863bd10ec3))
+
+## 2.0.0-beta.3
+
+### Bug Fixes
+
+- set up filters beforehand so they're accessible in permalinks ([58a4992](https://github.com/noelforte/eleventy-plugin-vento/commit/58a4992ea56778d8da28869c3ae06a499243cf90))
+
+## 2.0.0-beta.2
+
+### New Features
+
+- compile permalinks with vento using instance configuration ([170dc4d](https://github.com/noelforte/eleventy-plugin-vento/commit/170dc4d5a45f8a3dd25f57b99cfea9db8196a820))
+
+## 1.1.3
+
+### Bug Fixes
+
+- move cache clearing to compile step, rather than eleventy.before. ([44a424c](https://github.com/noelforte/eleventy-plugin-vento/commit/44a424cf0b10b641f67aadba0670f112e6e0d06c))
+
+## 2.0.0-beta.1
+
+### ⚠ BREAKING CHANGES
+
+The 2.0.0 release of this plugin does away with a separate filters object and defers all filter handling to Eleventy. This way any filters you already have in your Eleventy code don't have to be defined twice. If this project had started with a 0.x.x version then I wouldn't be pushing 2.0 out this fast, but I'm new to releasing npm packages so we started on 1.0. Thanks for your patience as I learn the ins and outs of SemVer!!
+
+### New Features
+
+- rework filters to pull from eleventy definitions rather than defining a separate object ([a98355a](https://github.com/noelforte/eleventy-plugin-vento/commit/a98355a8a0fcdc8f63ba507997f1a5e93b0b266a))
+- wire up internal autoTrim plugin as trimTags option ([7756c06](https://github.com/noelforte/eleventy-plugin-vento/commit/7756c06f02ccbab5a689909e66733d09d1ab2c19))
+
+### Bug Fixes
+
+- add exports to package.json ([b07c53b](https://github.com/noelforte/eleventy-plugin-vento/commit/b07c53bc6a804608ad7a395a1f1e8d540ebaded8))
+- exports from VentoPlugin and imports/syntax on eleventy.config.js ([f719c99](https://github.com/noelforte/eleventy-plugin-vento/commit/f719c990580241c343e7e2c0753926a6086d4e32))
+
+## 1.1.2
+
+### Bug Fixes
+
+- compile permalinks properly so permalinks starting with `/` don't default to their `permalink` values ([fc69db5](https://github.com/noelforte/eleventy-plugin-vento/commit/fc69db5b60acb0ba1a0aa5247ad71ace6610c3b7))
+
+## v1.1.1
+
+Add example to docs showing examples for loading plugins.
+
+## v1.1.0
+
+- Add ability to load Vento plugins.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Noel Forte
+Copyright (c) Noel Forte <noel@forte.is> (https://forte.is/)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,57 +1,62 @@
 {
-	"name": "eleventy-plugin-vento",
-	"version": "2.6.0",
-	"description": "Adds support for the Vento templating language to Eleventy.",
-	"type": "module",
-	"packageManager": "pnpm@9.5.0",
-	"engines": {
-		"node": ">=16"
-	},
-	"scripts": {
-		"test": "vitest",
-		"lint": "eslint **/*.js --config ./eslint.config.js"
-	},
-	"main": "./VentoPlugin.js",
-	"imports": {
-		"#lib/*": "./lib/*",
-		"#test-instance": "./tests/get-instance.js"
-	},
-	"exports": {
-		".": "./VentoPlugin.js"
-	},
-	"repository": "git@github.com:noelforte/eleventy-plugin-vento.git",
-	"bugs": {
-		"url": "https://github.com/noelforte/eleventy-plugin-vento/issues"
-	},
-	"keywords": [
-		"eleventy",
-		"eleventy-plugin",
-		"ventojs",
-		"templating"
-	],
-	"author": {
-		"name": "Noel Forte",
-		"email": "noel@forte.is",
-		"url": "https://forte.is/"
-	},
-	"license": "MIT",
-	"dependencies": {
-		"ventojs": "0.12.9"
-	},
-	"devDependencies": {
-		"@11ty/eleventy": "3.0.0-alpha.14",
-		"conventional-changelog-conventionalcommits": "8.0.0",
-		"eslint": "9.6.0",
-		"eslint-config-flat-gitignore": "0.1.7",
-		"eslint-config-prettier": "9.1.0",
-		"globals": "15.8.0",
-		"semantic-release": "24.0.0",
-		"vitest": "2.0.2"
-	},
-	"prettier": {
-		"bracketSameLine": true,
-		"singleQuote": true,
-		"semi": true,
-		"trailingComma": "es5"
-	}
-}
+  "name": "eleventy-plugin-vento",
+  "version": "3.0.1",
+  "description": "Adds support for the Vento templating language to Eleventy.",
+  "type": "module",
+  "engines": {
+    "node": ">=16"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    }
+  },
+  "repository": "git@github.com:noelforte/eleventy-plugin-vento.git",
+  "bugs": {
+    "url": "https://github.com/noelforte/eleventy-plugin-vento/issues"
+  },
+  "keywords": [
+    "eleventy",
+    "eleventy-plugin",
+    "ventojs",
+    "templating"
+  ],
+  "author": {
+    "name": "Noel Forte",
+    "email": "noel@forte.is",
+    "url": "https://forte.is/"
+  },
+  "license": "MIT",
+  "files": [
+    "src/*",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "ventojs": "1.12.10"
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "3.0.0-beta.1",
+    "@changesets/cli": "2.27.8",
+    "eslint": "9.11.1",
+    "eslint-config-flat-gitignore": "0.3.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-unicorn": "55.0.0",
+    "globals": "15.9.0",
+    "vitest": "2.1.1",
+    "zx": "8.1.8"
+  },
+  "prettier": {
+    "bracketSameLine": true,
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "es5"
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "lint": "eslint '**/*.js'",
+    "ci:version": "npm audit signatures && changeset version && pnpm install --no-frozen-lockfile",
+    "ci:publish": "changeset publish",
+    "ci:generate-changesets": "node ./scripts/generate-changesets.js",
+    "format": "pnpm dlx prettier --config ./package.json --write ."
+  }
+}

package/readme.md

@@ -1,8 +1,9 @@
 # eleventy-plugin-vento 🌬️🎈🐀
 
+<img src="https://img.shields.io/badge/Eleventy-v3_&amp;_later_-333?style=flat-square&logo=eleventy&logoColor=fff&labelColor=333&color=111" alt="Eleventy v3 and later">
 <a href="https://github.com/noelforte/eleventy-plugin-vento/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/noelforte/eleventy-plugin-vento/ci.yml?branch=main&style=flat-square&logo=github&logoColor=fff&label=Tests&labelColor=333" alt="Github Actions Status"></a>
 <a href="https://npmjs.com/package/eleventy-plugin-vento"><img src="https://img.shields.io/npm/v/eleventy-plugin-vento?style=flat-square&logo=npm&logoColor=fff&labelColor=333" alt="eleventy-plugin-vento on npm"></a>
-<a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/semantic--release-Conventional_Commits-fa6673?style=flat-square&logo=semanticrelease&logoColor=fff&labelColor=333" alt="semantic-release"></a>
+<a href="https://github.com/changesets/changesets/"><img src="https://img.shields.io/badge/🦋_Changesets-333?style=flat-square" alt="changesets on GitHub"></a>
 
 An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://vento.js.org/) templates.
 
@@ -12,10 +13,10 @@ An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://ve
 [Usage](#usage)<br>
 [Plugin Options](#plugin-options)<br>
 [Filters](#filters)<br>
+[Shortcodes (Single & Paired)](#shortcodes-single--paired)<br>
 [Vento Plugins](#vento-plugins)<br>
 [Auto-Trimming Tags](#auto-trimming-tags)<br>
-[JavaScript Helpers](#javascript-helpers)<br>
-[Hybrid Rendering](#hybrid-rendering)<br>
+[Ignoring Tags](#ignoring-tags)<br>
 
 ## Installing
 
@@ -25,9 +26,9 @@ npm install eleventy-plugin-vento
 
 ## Usage
 
-This plugin is ESM only and cannot be required from CommonJS. As such, it's best used with Eleventy v3.0.0.
+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 v1.0.0 which added support for [Custom Templates](https://www.11ty.dev/docs/languages/custom/).
+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:
 
@@ -48,21 +49,25 @@ import { VentoPlugin } from 'eleventy-plugin-vento';
 
 export default function (eleventyConfig) {
   eleventyConfig.addPlugin(VentoPlugin, {
-    // An array of Vento plugins to load
+    // An array of Vento plugins to use when compiling
     plugins: [],
 
-    // Define whether Javascript Functions should be added
-    // to page data. See below for usage notes on this.
-    addHelpers: true,
+    // 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)
-    trimTags: [],
+    autotrim: false,
+
+    // Enable/disable ignore tag syntax (see section on ignoring tags)
+    ignoreTag: false,
 
     // A Vento configuration object
     ventoOptions: {
-      includes: '...', // defaults to the Eleventy 'includes' directory
-      autoescape: false,
+      includes: eleventyConfig.directories.includes,
     },
   });
 }
@@ -72,14 +77,75 @@ View the [full list of options](https://vento.js.org/configuration/#options/) to
 
 ## Filters
 
-Filters that are added using 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.
+> [!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:
+>
+> ```nunjucks
+> {{ 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](https://vento.js.org/configuration/#filters) and [Pipes](https://vento.js.org/syntax/pipes/)
+
+Eleventy: See [Filters](https://www.11ty.dev/docs/filters/)
+
+## Shortcodes (Single & Paired)
 
-[More information about Vento filters](https://vento.js.org/configuration/#filters)
+> [!NOTE]
+> Remember, Vento can print any return value from a Javascript expression, as well as [run arbitrary JavaScript](https://vento.js.org/syntax/javascript/) in templates through its `{{> ...}}` operator. In these cases, shortcodes may not be needed depending on your usage.
 
-[More information about Eleventy filters](https://www.11ty.dev/docs/filters/)
+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:
+
+```nunjucks
+{{ 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.)
+
+```nunjucks
+{{ 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).
+
+```nunjucks
+{{ 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](https://www.11ty.dev/docs/shortcodes/) and the sub-section on [Paired Shortcodes](https://www.11ty.dev/docs/shortcodes/#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](#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.
 
 ```js
@@ -91,7 +157,7 @@ function myCustomPlugin() {
 
 export default function (eleventyConfig) {
   eleventyConfig.addPlugin(VentoPlugin, {
-    plugins: [myCustomPlugin()],
+    plugins: [myCustomPlugin],
   });
 }
 ```
@@ -100,94 +166,50 @@ export default function (eleventyConfig) {
 
 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 the default tags, set the `trimTags` plugin option to `true`.
+To trim space around the default tags and all Eleventy paired shortcodes, set the `autotrim` plugin option to `true`.
 
 ```js
 eleventyConfig.addPlugin(VentoPlugin, {
-  trimTags: true,
+  autotrim: true,
 });
 ```
 
-The default set of tags that are trimmed are defined by Vento and are listed in the [usage notes](https://vento.js.org/plugins/auto-trim/#usage) for the auto trim plugin. To set your own tags, set `trimTags` to an array instead.
+The default set of tags that are trimmed are [defined by Vento itself](https://github.com/ventojs/vento/blob/8c767d45441c2d5a90b6b2b4e33bec56018807d3/plugins/auto_trim.ts#L4-L20). To set your own list of tags, set `autotrim` to an array of tags:
 
 ```js
 eleventyConfig.addPlugin(VentoPlugin, {
-  trimTags: ['set', 'if', 'for'],
+  autotrim: ['set', 'if', 'for'],
 });
 ```
 
-If instead, you'd like to extend instead of replace the default tag list, `eleventy-plugin-vento` reexports the `defaultTags` array used by as `ventoDefaultTrimTags`, which can be used like so:
+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.
 
 ```js
-import { VentoPlugin, ventoDefaultTrimTags } from 'eleventy-plugin-vento';
+import { VentoPlugin } from 'eleventy-plugin-vento';
 
 eleventyConfig.addPlugin(VentoPlugin, {
-  trimTags: [...ventoDefaultTrimTags, 'tag'],
+  autotrim: {
+    tags: ['@vento', '@11ty', 'tag'],
+  },
 });
 ```
 
-For more information on the auto-trim plugin, consult the [plugin documentation](https://vento.js.org/plugins/auto-trim/).
+### Relevant documentation
 
-## JavaScript Helpers
+Vento: See [Auto Trim Plugin](https://vento.js.org/plugins/auto-trim/).
 
-Vento can [run arbitrary JavaScript](https://vento.js.org/syntax/javascript/) in templates through its `{{> ...}}` operator, which evaluates at the time the template is run. However, you may want to use Eleventy Shortcodes and Filters in your templates as well.
+## Ignoring Tags
 
-By setting `addHelpers` in the plugin options (defaults to `true`), all JavaScript functions (which includes any Universal Shortcodes) are exposed as functions in page data. This feature functions very similarly to WebC's ["helper functions"](https://www.11ty.dev/docs/languages/javascript/#javascript-template-functions) feature.
-
-As an example:
-
-```js
-export default function (eleventyConfig) {
-  // via Universal Filter...
-  eleventyConfig.addFilter('italicize', (content) => `<em>${content}</em>`);
-
-  // ...or via Universal Shortcode
-  eleventyConfig.addShortcode('greeting', (name) => `My name is ${name}`);
-
-  // ...or via JavaScript Template Function
-  eleventyConfig.addJavaScriptFunction('possumPosse', () => 'Release the possums!!!');
-}
-```
-
-```hbs
-<p>This is something {{ italicize('really') }} important.</p>
-<p>{{ possumPosse() }}</p>
-
-<!-- renders as: -->
-
-<p>This is something <em>really</em> important.</p>
-<p>Release the possums!!!</p>
-
-```
-
-Alternatively, if you'd rather keep functions namespaced in your page data, pass a string to `addHelpers`. Your functions will be namespaced under this property name in page data.
-
-```js
-addPlugin(VentoPlugin, { addHelpers: 'functions' });
-```
-
-```nunjucks
-<!-- With the above, this: -->
-<p>This is something {{ italicize('really') }} important.</p>
-<p>{{ possumPosse() }}</p>
-
-<!-- should be written as: -->
-<p>This is something {{ functions.italicize('really') }} important.</p>
-<p>{{ functions.possumPosse() }}</p>
-```
+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.
 
-Finally, if you'd like to disable populating helper functions at all, set `addHelpers` to false:
+This feature is enabled through use of the `enableIgnoreTag` plugin option.
 
 ```js
 eleventyConfig.addPlugin(VentoPlugin, {
-  addHelpers: false,
+  enableIgnoreTag: true,
 });
 ```
 
-## Hybrid Rendering
-
-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.
-
 To skip over a tag, add a `!` directly after the opening tag.
 
 ```nunjucks
@@ -240,6 +262,6 @@ Rather than having to do multiple `{{ /echo }} ... {{ echo }}` statements, the p
 {{ if someCondition }}
   <p>{{ getServerData }}</p>
 
-  <p>Page built on: 04-08-2024</p>
+  <p>Page built on: 09-19-2024</p>
 {{ /if }}
 ```