eleventy-plugin-vento 1.0.4

package/.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 2
+trim_trailing_whitespace = true
+max_line_length = 100
+
+[*.{yaml,yml,md}]
+indent_style = space

package/.github/renovate.json

@@ -0,0 +1,13 @@
+{
+	"extends": ["github>noelforte/renovate-config", "group:allNonMajor"],
+	"customManagers": [
+		{
+			"customType": "regex",
+			"fileMatch": ["(^|\\/)\\.mise\\.toml$"],
+			"matchStrings": [
+				"#renovate: datasource=(?<datasource>\\S+)(\\s|\\sversioning=(?<versioning>\\S+)\\s)(?<depName>\\S+)\\s?=\\s?\"(?<currentValue>[^\\\"]+)\""
+			],
+			"versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
+		}
+	]
+}

package/.github/workflows/ci.yaml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [renovate/**]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      # ========== SETUP ========== #
+      - name: Check out repository
+        uses: actions/checkout@v4.1.6
+
+      # Setup node
+      - name: Setup tools
+        uses: jdx/mise-action@v2
+
+      # Setup pnpm
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4.0.0
+
+      # Get metadata
+      - name: Get pnpm store directory
+        id: get-pnpm-store
+        shell: bash
+        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+      # Setup the cache
+      - uses: actions/cache@v4
+        name: Restore cache
+        id: cache-deps
+        with:
+          path: ${{ steps.get-pnpm-store.outputs.path }}
+          key:
+            deps_os-${{ runner.os }}_arch-${{ runner.arch }}_${{
+            hashFiles('./pnpm-lock.yaml') }}
+
+      # Install dependencies
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+        shell: bash
+
+      # ========== CHECK ========== #
+      - name: Run checks
+        run: pnpm test
+        shell: bash

package/.mise.toml

@@ -0,0 +1,3 @@
+[tools]
+#renovate: datasource=node-version versioning=node
+node = "20.14.0"

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"cSpell.words": ["Vento"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Noel Forte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/VentoPlugin.js

@@ -0,0 +1,75 @@
+/**
+ * @file Adds Vento support to Eleventy.
+ *
+ * @typedef VentoPluginOptions
+ * @prop {Object<string,(...any) => any} [filters={}] An object containing methods that
+ * will be loaded as filters into Vento.
+ * @prop {import('ventojs').Options} [ventoOptions] Vento engine configuration object
+ * that will be merged with default options.
+ * @prop {string|boolean} [addHelpers=true] Whether
+ * [Javascript Functions](https://www.11ty.dev/docs/languages/javascript/#javascript-template-functions)
+ * should be merged into data provided to templates. If a string, functions will be namespaced under
+ * a property with this name.
+ */
+
+import path from 'node:path';
+import VentoJs from 'ventojs';
+
+/**
+ * @param {import('@11ty/eleventy/src/UserConfig.js').default} eleventyConfig
+ * @param {VentoPluginOptions} options
+ */
+export function VentoPlugin(eleventyConfig, options = {}) {
+	if (!('addExtension' in eleventyConfig)) {
+		console.log(
+			`[eleventy-plugin-vento] WARN Eleventy plugin compatibility: Custom templates are required for this plugin, please use Eleventy v1.0 or newer.`
+		);
+	}
+
+	// Pull some bits from eleventyConfig and merge user-options with defaults
+	const { dir, javascriptFunctions } = eleventyConfig;
+	options = {
+		addHelpers: true,
+		filters: {},
+		ventoOptions: {
+			includes: path.join(dir.input, dir.includes),
+			autoescape: false,
+		},
+		...options,
+	};
+
+	// Init vento
+	const env = VentoJs(options.ventoOptions);
+
+	// Load user-defined filters into vento
+	for (const filter in options.filters) env.filters[filter] = options.filters[filter];
+
+	eleventyConfig.on('eleventy.before', () => {
+		env.cache.clear();
+	});
+
+	// Add vto as a template format and create a custom template for it
+	eleventyConfig.addTemplateFormats('vto');
+	eleventyConfig.addExtension('vto', {
+		outputFileExtension: 'html',
+		async compile(inputContent, inputPath) {
+			return async (data) => {
+				if (options.addHelpers) {
+					// Extract a possible namespace from the addHelpers option
+					const namespace = options.addHelpers;
+
+					// Rebind functions to page data so this.page, this.eleventy, etc works as intended
+					const helpers = Object.assign(
+						...Object.entries(javascriptFunctions).map(([name, fn]) => ({ [name]: fn.bind(data) }))
+					);
+
+					// Merge helpers into page data
+					if (typeof namespace === 'string') data = { ...data, [namespace]: helpers };
+					else data = { ...data, ...helpers };
+				}
+
+				return await env.runString(inputContent, data, inputPath).then((result) => result.content);
+			};
+		},
+	});
+}

package/eslint.config.js

@@ -0,0 +1,67 @@
+import js from '@eslint/js';
+
+// Configs
+import gitignore from 'eslint-config-flat-gitignore';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+// Plugins
+import globals from 'globals';
+
+export default [
+	// Set ignores from gitignore
+	gitignore(),
+
+	// Import configuration presets
+	js.configs.recommended,
+	eslintConfigPrettier,
+
+	// Configure ignores
+	{
+		ignores: ['**/.cache', '**/_site', '**/node_modules', '**/functions'],
+	},
+
+	// Configure defaults
+	{
+		languageOptions: {
+			ecmaVersion: 'latest',
+		},
+		rules: {
+			'no-unused-vars': [
+				'error',
+				{
+					argsIgnorePattern: '^_',
+				},
+			],
+			'no-else-return': [
+				'error',
+				{
+					allowElseIf: false,
+				},
+			],
+			'prefer-regex-literals': ['error', { disallowRedundantWrapping: true }],
+			'prefer-object-spread': 'error',
+			'prefer-const': ['error', { destructuring: 'all' }],
+			'prefer-arrow-callback': ['error', { allowNamedFunctions: true }],
+			'prefer-destructuring': [
+				'error',
+				{
+					VariableDeclarator: { array: false, object: true },
+					AssignmentExpression: { array: false, object: false },
+				},
+			],
+			'object-shorthand': ['error', 'always'],
+			'arrow-body-style': ['error', 'as-needed'],
+			eqeqeq: ['error', 'smart'],
+		},
+	},
+
+	// Match all node-files
+	{
+		files: ['**/*.js'],
+		languageOptions: {
+			globals: {
+				...globals.node,
+			},
+		},
+	},
+];

package/jsconfig.json

@@ -0,0 +1,6 @@
+{
+	"compilerOptions": {
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext"
+	}
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "eleventy-plugin-vento",
+	"version": "1.0.4",
+	"description": "Adds support for the Vento templating language to Eleventy",
+	"type": "module",
+	"packageManager": "pnpm@9.1.4",
+	"scripts": {
+		"test": "rm -rf test/output; cd test/input; eleventy",
+		"test-serve": "rm -rf test/output; cd test/input; eleventy --serve"
+	},
+	"main": "./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.6"
+	},
+	"devDependencies": {
+		"eslint": "9.4.0",
+		"eslint-config-flat-gitignore": "0.1.5",
+		"eslint-config-prettier": "9.1.0",
+		"globals": "15.3.0",
+		"@11ty/eleventy": "3.0.0-alpha.10"
+	},
+	"prettier": {
+		"bracketSameLine": true,
+		"singleQuote": true,
+		"semi": true,
+		"trailingComma": "es5"
+	}
+}

package/readme.md

@@ -0,0 +1,132 @@
+# eleventy-plugin-vento 🌬️🎈🐀
+
+An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://vento.js.org/) templates.
+
+[Installing](#installing)<br>
+[Usage](#usage)<br>
+[Plugin Options](#plugin-options)<br>
+[Vento Filters](#vento-filters)<br>
+[JavaScript Helpers](#javascript-helpers)<br>
+
+## Installing
+
+```sh
+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.
+
+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/).
+
+In your Eleventy config:
+
+```js
+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](https://www.11ty.dev/docs/plugins/#plugin-configuration-options) to your `addPlugin` call to configure things further. The below example shows the configurable options as well as their defaults.
+
+```js
+import { VentoPlugin } from 'eleventy-plugin-vento';
+
+export default function (eleventyConfig) {
+
+  eleventyConfig.addPlugin(VentoPlugin, {
+    // A set of filters to load into Vento
+    filters: {},
+
+    // Define whether Javascript Functions should be added
+    // to page data. See below for usage notes on this.
+    addHelpers: true
+
+    // A Vento configuration object
+    ventoOptions: {
+      includes: '...', // defaults to the Eleventy 'includes' directory
+      autoescape: false,
+    },
+  });
+
+}
+```
+
+View the [full list of options](https://vento.js.org/configuration/#options/) to pass as a Vento Configuration object.
+
+## Vento Filters
+
+Set the `filters` property to an object with methods, these will be loaded as filters into Vento when Eleventy is run. Note that this feature exists **separately** from the concept of filters in Eleventy ([which are optionally accessible as data in Vento templates]()).
+
+Here's an example of defining an `italicize` filter like the example in the Vento documentation:
+
+```js
+{
+  filters: {
+    italicize(text) {
+      return `<em>${text}</em>`
+    }
+  }
+}
+```
+
+And now we can use our filter in a template:
+
+```hbs
+<p>The title of my page is: "{{ title |> italicize }}"</p>
+```
+
+See https://vento.js.org/configuration/#filters for more information about filters and how they work.
+
+## JavaScript Helpers
+
+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.
+
+By setting `addHelpers` in the plugin options (defaults to `true`), all JavaScript functions (which includes any Universal Filters and 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' });
+```
+
+```hbs
+<!-- 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>
+```

package/test/input/_includes/page-layout-alt.vto

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>{{ title }}</title>
+	</head>
+	<body>
+		<header>
+			<h1>Page title: {{ title }}</h1>
+		</header>
+		<main>
+			<section>This is an alternative layout.</section>
+			<section>{{ content }}</section>
+		</main>
+		<footer>
+			<p>I am a footer, outside the layout</p>
+		</footer>
+	</body>
+</html>

package/test/input/_includes/page-layout.vto

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>{{ title }}</title>
+	</head>
+	<body>
+		<header>
+			<h1>Page title: {{ title }}</h1>
+		</header>
+		<main>{{ content }}</main>
+		<footer>
+			<p>I am a footer, outside the layout</p>
+		</footer>
+	</body>
+</html>

package/test/input/_includes/partial.vto

@@ -0,0 +1,3 @@
+<section class="include">
+	<p>This content is included.</p>
+</section>

package/test/input/eleventy.config.js

@@ -0,0 +1,21 @@
+import { VentoPlugin } from '../../VentoPlugin.js';
+
+export const config = {
+	dir: {
+		input: '.',
+		output: '../output',
+	},
+};
+
+/** @param {import('@11ty/eleventy/src/UserConfig.js').default} eleventyConfig */
+export default async function (eleventyConfig) {
+	eleventyConfig.addPlugin(VentoPlugin, {
+		filters: {
+			italicize(content) {
+				return `<em>${content}</em>`;
+			},
+		},
+	});
+
+	eleventyConfig.addShortcode('possumPosse', () => 'Release the possums!!!');
+}

package/test/input/filters.vto

@@ -0,0 +1,9 @@
+---
+title: Page with filters
+---
+
+<h1>{{ title }}</h1>
+
+This is a page with a filter.
+
+Built with {{ eleventy.generator |> italicize }}

package/test/input/simple.vto

@@ -0,0 +1,7 @@
+---
+title: Simple Page
+---
+
+<h1>{{ title }}</h1>
+
+This is a standalone page.

package/test/input/with-includes.vto

@@ -0,0 +1,7 @@
+---
+title: Page with includes
+---
+
+<h1>{{ title }}</h1>
+
+{{ include 'partial.vto' }}

package/test/input/with-layout.vto

@@ -0,0 +1,11 @@
+---
+title: Page with layout
+layout: page-layout.vto
+---
+
+<p>This is a page that uses a layout.</p>
+
+<p>This is another paragraph.</p>
+<p>This is another paragraph.</p>
+<p>This is another paragraph.</p>
+

package/test/input/with-shortcodes.vto

@@ -0,0 +1,6 @@
+---
+title: Page with shortcodes
+layout: page-layout.vto
+---
+
+{{ possumPosse() }}