eleventy-plugin-vento 2.6.0 → 3.0.0

package/src/engine.js

@@ -0,0 +1,85 @@
+/**
+ * @file Class to facilitate ventojs processing
+ *
+ * @typedef {{eleventy?: Record<string, unknown>, page?: Record<string, unknown>}} EleventyContext
+ * @typedef {Context & Record<string, unknown>} EleventyData
+ * @typedef {(...args: unknown[]) => unknown} EleventyFunction
+ * @typedef {import('ventojs/src/environment.js').Environment} VentoEnvironment
+ * @typedef {VentoEnvironment & { _11ty: { ctx: Context, tags: Record<string, EleventyFunction> }}} EleventyVentoEnvironment
+ */
+
+// External library
+import ventojs from 'ventojs';
+
+// Internal modules
+import { createVentoTag } from './modules/create-vento-tag.js';
+
+// TODO: Update this if it becomes possible to import `augmentKeys` from Eleventy.
+const DATA_KEYS = ['page', 'eleventy'];
+
+export class VentoEngine {
+	#env;
+
+	/** @param {import('ventojs/src/environment.js').Options} options */
+	constructor(options) {
+		/** Initialize vento @type {EleventyVentoEnvironment} */
+		this.#env = ventojs(options);
+		this.#env._11ty = { ctx: {}, functions: {} };
+	}
+
+	/** @param {string?} key */
+	emptyCache(key) {
+		return key ? this.#env.cache.delete(key) : this.#env.cache.clear();
+	}
+
+	/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
+	loadPlugins(plugins) {
+		for (const plugin of plugins) {
+			this.#env.use(plugin);
+		}
+	}
+
+	/** @param {PageData} newContext  */
+	loadContext(newContext) {
+		// Loop through allowed keys and load those into the context
+		for (const key of DATA_KEYS) {
+			this.#env._11ty.ctx[key] = newContext[key];
+		}
+	}
+
+	/** @param {Record<string, EleventyFunction>} filters */
+	loadFilters(filters) {
+		for (const [name, fn] of Object.entries(filters)) {
+			this.#env.filters[name] = (...args) => fn.apply(this.#env._11ty.ctx, args);
+		}
+	}
+
+	/**
+	 * @param {Record<string, EleventyFunction>} shortcodes
+	 * @param {boolean} paired
+	 */
+	loadShortcodes(shortcodes, paired = false) {
+		for (const [name, fn] of Object.entries(shortcodes)) {
+			this.#env._11ty.functions[name] = fn;
+			this.#env.tags.push(createVentoTag(name, paired));
+		}
+	}
+
+	/**
+	 * @param {PageData} data
+	 * @param {string} content
+	 * @param {string} path
+	 */
+	async process(data, content, path) {
+		// Reload context
+		this.loadContext(data);
+
+		// Process the templates
+		const result = await this.#env.runString(content, data, path);
+
+		// Clear the cache for this path if the input doesn't match
+		if (data.page?.rawInput !== content) this.#env.cache.clear(path);
+
+		return result.content;
+	}
+}

package/src/index.js

@@ -0,0 +1,130 @@
+/**
+ * @file Main plugin declaration
+ *
+ * @typedef VentoPluginOptions
+ * @prop {import('ventojs/src/environment.js').Plugin[]} plugins
+ * Array of vento plugins to use when compiling templates
+ * @prop {boolean|string[]} autotrim
+ * Enable Vento's [`autoTrim`](https://vento.js.org/plugins/auto-trim/)
+ * plugin to remove whitespace from tags in output
+ * @prop {boolean} [shortcodes=true]
+ * Create vento tags for Eleventy [Shortcodes](https://www.11ty.dev/docs/shortcodes/)
+ * @prop {boolean} [pairedShortcodes=true]
+ * Create vento tags for Eleventy [Paired Shortcodes](https://www.11ty.dev/docs/shortcodes/#paired-shortcodes)
+ * @prop {boolean} [filters=true]
+ * Create vento filters for Eleventy [Filters](https://www.11ty.dev/docs/filters/)
+ * @prop {boolean} [ignoreTag=false]
+ * Enables/disables tag ignore (`{{! ... }}`) syntax in templates
+ * @prop {import('ventojs').Options} ventoOptions
+ * Options to pass on to the `ventojs` engine.
+ * (See [Vento Docs](https://vento.js.org/configuration/#options))
+ */
+
+// External modules
+import autotrimPlugin, { defaultTags as autotrimDefaultTags } from 'ventojs/plugins/auto_trim.js';
+
+// Local modules
+import { VentoEngine } from './engine.js';
+import { ignoreTagPlugin } from './modules/ignore-tag.js';
+import { runCompatibilityCheck } from './modules/utils.js';
+
+/**
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {Partial<VentoPluginOptions>} userOptions
+ */
+export function VentoPlugin(eleventyConfig, userOptions) {
+	runCompatibilityCheck(eleventyConfig);
+
+	/** @type {VentoPluginOptions} */
+	const options = {
+		// Define defaults
+		autotrim: false,
+		plugins: [],
+		filters: true,
+		shortcodes: true,
+		pairedShortcodes: true,
+		ignoreTag: false,
+		ventoOptions: {
+			includes: eleventyConfig.directories.includes,
+		},
+
+		// Merge in user-provided options
+		...userOptions,
+	};
+
+	// Get list of filters, shortcodes and paired shortcodes
+	const filters = eleventyConfig.getFilters();
+	const shortcodes = eleventyConfig.getShortcodes();
+	const pairedShortcodes = eleventyConfig.getPairedShortcodes();
+
+	// Add autotrim plugin if enabled
+	if (options.autotrim) {
+		const defaults = ['@vento', '@11ty'];
+
+		/** @type {Set<string>} */
+		const tagSet = new Set(options.autotrim === true ? defaults : options.autotrim);
+
+		if (tagSet.has('@vento')) {
+			tagSet.delete('@vento');
+			for (const name of autotrimDefaultTags) {
+				tagSet.add(name);
+			}
+		}
+
+		if (tagSet.has('@11ty')) {
+			tagSet.delete('@11ty');
+			for (const name in pairedShortcodes) {
+				tagSet.add(name);
+			}
+		}
+
+		options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
+	}
+
+	// Add ignore tag plugin if enabled
+	if (options.ignoreTag) {
+		options.plugins.push(ignoreTagPlugin);
+	}
+
+	// Create the vento engine instance
+	const vento = new VentoEngine(options.ventoOptions);
+
+	// Ensure cache is empty
+	vento.emptyCache();
+
+	// Load plugins
+	vento.loadPlugins(options.plugins);
+
+	// Add filters, single and paired shortcodes if enabled
+	if (options.filters) {
+		vento.loadFilters(filters);
+	}
+	if (options.shortcodes) {
+		vento.loadShortcodes(shortcodes, false);
+	}
+	if (options.pairedShortcodes) {
+		vento.loadShortcodes(pairedShortcodes, true);
+	}
+
+	// Add vto as a template format
+	eleventyConfig.addTemplateFormats('vto');
+
+	// Add extension handling
+	eleventyConfig.addExtension('vto', {
+		outputFileExtension: 'html',
+		read: true,
+
+		// Main compile function
+		async compile(inputContent, inputPath) {
+			return async (data) => vento.process(data, inputContent, inputPath);
+		},
+
+		// Custom permalink compilation
+		compileOptions: {
+			permalink(linkContents) {
+				if (typeof linkContents !== 'string') return linkContents;
+				return async (data) => vento.process(data, linkContents);
+			},
+		},
+	});
+}

package/src/modules/create-vento-tag.js

@@ -0,0 +1,56 @@
+/**
+ * @file Helper function that creates vento tags from eleventy functions
+ *
+ * @param {string} name
+ * @param {boolean} paired
+ */
+
+export function createVentoTag(name, paired) {
+	/** @type {import("ventojs/src/environment.js").Tag} */
+	const tag = (env, code, output, tokens) => {
+		if (!code.startsWith(name)) return;
+
+		// Declare helper object path strings
+		const fn = `__env._11ty.functions.${name}`;
+		const ctx = '__env._11ty.ctx';
+		let args = [code.replace(name, '').trim()];
+
+		const varname = output.startsWith('__shortcode_content')
+			? `${output}_precomp`
+			: '__shortcode_content';
+
+		// Create an array to hold compiled template code
+		const compiled = [];
+
+		if (paired) {
+			args.unshift(env.compileFilters(tokens, varname, env.options.autoescape));
+			compiled.push(
+				'{',
+				`let ${varname} = "";`,
+				...env.compileTokens(tokens, varname, [`/${name}`])
+			);
+			if (tokens.length > 0 && (tokens[0][0] !== 'tag' || tokens[0][1] !== `/${name}`)) {
+				throw new Error(`Missing closing tag for ${name} tag: ${code}`);
+			}
+			tokens.shift();
+		}
+
+		// Compile arguments into a string
+		args = args.some(Boolean) ? `, ${args.filter(Boolean).join(', ')}` : '';
+
+		compiled.push(
+			'{',
+			`const __shortcode_result = await ${fn}.call(${ctx + args});`,
+			`${output} += ${env.compileFilters(tokens, '__shortcode_result', env.options.autoescape)}`,
+			'}'
+		);
+
+		if (paired) compiled.push('}');
+
+		// console.log(compiled);
+
+		return compiled.join('\n');
+	};
+
+	return Object.defineProperty(tag, 'name', { value: paired ? `${name}PairedTag` : `${name}Tag` });
+}

package/src/modules/ignore-tag.js

@@ -0,0 +1,15 @@
+/**
+ * @file Definition for tag that preserves vento syntax in output
+ */
+
+/** @type {import('ventojs/src/environment.js').Tag} */
+function ignoreTag(_env, code, output, _tokens) {
+	if (!code.startsWith('!')) return;
+	const compiled = `{{${code.replace(/!(>?)\s+/, '$1 ')}}}`;
+	return `${output} += "${compiled}";`;
+}
+
+/** @type {import('ventojs/src/environment.js').Plugin} */
+export function ignoreTagPlugin(env) {
+	env.tags.push(ignoreTag);
+}

package/src/modules/utils.js

@@ -0,0 +1,22 @@
+// Declare required APIs
+const REQUIRED_API_METHODS = [
+	['getShortcodes', 'v3.0.0-alpha.15'],
+	['getPairedShortcodes', 'v3.0.0-alpha.15'],
+	['getFilters', 'v3.0.0-alpha.15'],
+	['addExtension', 'v1.0.0'],
+];
+
+export function logError(message) {
+	console.error(`[eleventy-plugin-vento] ${message}`);
+}
+
+/** @param {import("@11ty/eleventy").UserConfig} configApi */
+export function runCompatibilityCheck(configApi) {
+	for (const [method, version] of REQUIRED_API_METHODS) {
+		if (!configApi?.[method]) {
+			logError(
+				`Eleventy plugin compatibility error: '${method}' not available. Use Eleventy ${version} or later.`
+			);
+		}
+	}
+}

package/.editorconfig

@@ -1,16 +0,0 @@
-# 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/actions/setup/action.yml

@@ -1,25 +0,0 @@
-name: Setup
-description: Setup project with pnpm
-
-outputs:
-  cache-hit:
-    description: 'Whether restoring the cache was successful or not'
-    value: ${{ steps.setup-node.outputs.cache-hit }}
-
-runs:
-  using: composite
-  steps:
-    - name: Setup pnpm
-      uses: pnpm/action-setup@v4
-
-    - name: Setup node
-      id: setup-node
-      uses: actions/setup-node@v4
-      with:
-        node-version-file: .node-version
-        cache: pnpm
-        cache-dependency-path: pnpm-lock.yaml
-
-    - name: Install dependencies
-      run: pnpm install --frozen-lockfile
-      shell: bash

package/.github/renovate.json

@@ -1,13 +0,0 @@
-{
-	"extends": ["github>noelforte/renovate-config"],
-	"packageRules": [
-		{
-			"matchDepTypes": ["dependencies"],
-			"semanticCommitType": "upstream",
-			"semanticCommitScope": null
-		},
-		{
-			"matchDepTypes": ["devDependencies"]
-		}
-	]
-}

package/.github/workflows/ci.yml

@@ -1,15 +0,0 @@
-name: CI
-
-on: push
-
-jobs:
-  default:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup
-        uses: ./.github/actions/setup
-
-      - name: Test
-        run: pnpm test

package/.github/workflows/release.yml

@@ -1,33 +0,0 @@
-name: Release
-
-on:
-  workflow_run:
-    types: [completed]
-    workflows: [CI]
-    branches: [main, alpha, beta, next]
-
-jobs:
-  release:
-    if: github.event.workflow_run.conclusion == 'success'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write # to be able to publish a GitHub release
-      id-token: write # to enable use of OIDC for npm provenance
-      issues: write # to be able to comment on released issues
-      pull-requests: write # to be able to comment on released pull requests
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup
-        uses: ./.github/actions/setup
-
-      - name: Verify provenance attestations and registry signatures
-        run: npm audit signatures
-
-      - name: Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm exec semantic-release

package/.node-version

@@ -1 +0,0 @@
-20.15.1

package/.vscode/settings.json

@@ -1,4 +0,0 @@
-{
-	"cSpell.words": ["Vento"],
-	"deno.enable": false
-}

package/.vscode/tests.code-snippets

@@ -1,16 +0,0 @@
-{
-	"New test suite": {
-		"scope": "javascript",
-		"prefix": "VentoPluginTest",
-		"body": [
-			"import { expect, test } from 'vitest';",
-			"import { runBuild } from '#test-instance';\n",
-			"const results = await runBuild(import.meta.dirname, {",
-			"\t${1:eleventy(configApi) {\\}},",
-			"\t${2:vento: {\\}},",
-			"});"
-		],
-		"description": "Create a new test suite for eleventy-plugin-vento",
-		"isFileTemplate": true
-	}
-}

package/VentoPlugin.js

@@ -1,140 +0,0 @@
-/**
- * @file Adds support for the Vento templating language to Eleventy.
- *
- * @typedef VentoPluginOptions
- * @prop {Function[]} [plugins=[]] An array of plugins to load into vento.
- * @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.
- * @prop {boolean|string[]} [trimTags=false] Whether to automatically trim tags from output. Uses Vento's
- * [autoTrim](https://vento.js.org/plugins/auto-trim/) plugin under the hood.
- * @prop {import('ventojs').Options} [ventoOptions] Vento engine configuration object
- * that will be merged with default options.
- */
-
-import VentoJs from 'ventojs';
-import { ssr } from '#lib/ssr.js';
-
-// Expose autotrim plugin defaults
-import {
-	default as autoTrim,
-	defaultTags as ventoDefaultTrimTags,
-} from 'ventojs/plugins/auto_trim.js';
-export { ventoDefaultTrimTags };
-
-/**
- * @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 { directories, javascriptFunctions, liquidFilters, nunjucksFilters, nunjucksAsyncFilters } =
-		eleventyConfig;
-
-	options = {
-		addHelpers: true,
-		trimTags: false,
-		plugins: [],
-		ventoOptions: {
-			includes: directories.includes,
-			autoescape: false,
-		},
-		...options,
-	};
-
-	// Init vento
-	const env = VentoJs(options.ventoOptions);
-
-	// Create empty sets to hold user defined functions
-	const filters = {};
-	const helperFunctions = {};
-
-	for (const fn in javascriptFunctions) {
-		if (liquidFilters[fn] && (nunjucksFilters[fn] || nunjucksAsyncFilters[fn])) {
-			filters[fn] = javascriptFunctions[fn];
-		} else {
-			helperFunctions[fn] = javascriptFunctions[fn];
-		}
-	}
-
-	// Load filters into vento
-	for (const filter in filters) env.filters[filter] = filters[filter];
-
-	// Load user-defined plugins into vento
-	for (const plugin of options.plugins) env.use(plugin);
-
-	// Load ssr plugin
-	env.use(ssr);
-
-	// Add autotrim plugin if enabled
-	if (options.trimTags === true) env.use(autoTrim());
-	else if (options.trimTags) env.use(autoTrim({ tags: options.trimTags }));
-
-	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', {
-		// Set output extension
-		outputFileExtension: 'html',
-
-		// Read vto files into eleventy
-		read: true,
-
-		// Main compile function
-		async compile(inputContent, inputPath) {
-			return async (data) => {
-				if (options.addHelpers) {
-					// Extract a possible namespace from the addHelpers option
-					const namespace = options.addHelpers;
-
-					// Extract page and eleventy values from data
-					const { page, eleventy } = data;
-
-					// Rebind functions to page data so this.page, this.eleventy, etc works as intended
-					for (const helper in helperFunctions) {
-						helperFunctions[helper] = helperFunctions[helper].bind({
-							page,
-							eleventy,
-						});
-					}
-
-					// Rebind filters the same way
-					for (const filter in filters) {
-						env.filters[filter] = filters[filter].bind({ page, eleventy });
-					}
-
-					// Merge helpers into page data
-					if (typeof namespace === 'string') data = { ...data, [namespace]: helperFunctions };
-					else data = { ...data, ...helperFunctions };
-				}
-
-				const result = await env.runString(inputContent, data, inputPath);
-
-				if (data.page?.rawInput !== inputContent) {
-					env.cache.delete(inputPath);
-				}
-
-				return result.content;
-			};
-		},
-
-		compileOptions: {
-			// Custom permalink compilation
-			permalink(linkContents) {
-				if (typeof linkContents !== 'string') return linkContents;
-				return async (data) => {
-					const result = await env.runString(linkContents, data);
-					return result.content;
-				};
-			},
-		},
-	});
-}

package/eslint.config.js

@@ -1,67 +0,0 @@
-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: ['**/node_modules'],
-	},
-
-	// 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

@@ -1,11 +0,0 @@
-{
-	"compilerOptions": {
-		"module": "NodeNext",
-		"moduleResolution": "NodeNext",
-		"baseUrl": ".",
-		"paths": {
-			"#lib/*": ["./lib/*"],
-			"#test-instance": ["./tests/get-instance.js"]
-		}
-	}
-}

package/lib/ssr.js

@@ -1,23 +0,0 @@
-/**
- * @typedef {import('ventojs/src/tokenizer.js').Token} Token
- * @typedef {import('ventojs/src/environment.js').Environment} Environment
- */
-
-/** @param {Environment} env */
-export function ssr(env) {
-	env.tags.push(ssrTag);
-}
-
-/**
- * @param {string} code
- * @param {Environment} env
- * @param {string} output
- * @param {Token[]} tokens
- */
-function ssrTag(env, code, output, _tokens) {
-	if (!code.startsWith('!')) return;
-
-	const compiled = `{{${code.replace(/!(>?)\s+/, '$1 ')} }}`;
-
-	return `${output} += "${compiled}";`;
-}