@apleasantview/eleventy-plugin-baseline 0.1.0-next.29 → 0.1.0-next.33

package/eleventy.config.js

@@ -30,12 +30,14 @@ export default function baseline(options = {}) {
 	/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
 	const plugin = async function (eleventyConfig) {
 		try {
-			// Emit a warning message if the application is not using Eleventy 3.0 or newer (including prereleases).
 			eleventyConfig.versionCheck('>=3.0');
 		} catch (e) {
 			console.log(`[eleventy-plugin-baseline] WARN Eleventy plugin compatibility: ${e.message}`);
 		}
 
+		// --- Options ---
+		// Merge user options with defaults, detect environment capabilities,
+		// and expose everything as _baseline global data for templates.
 		const hasImageTransformPlugin = eleventyConfig.hasPlugin('eleventyImageTransformPlugin');
 
 		const userOptions = {
@@ -47,15 +49,15 @@ export default function baseline(options = {}) {
 			enableSitemapTemplate: options.enableSitemapTemplate ?? true,
 			filterAllCollection: options.filterAllCollection ?? true,
 			assets: {
-				esbuild: options.assetsESBuild ?? { minify: true, target: 'es2020' }
+				esbuild: options.assetsESBuild ?? {}
 			},
 			multilingual: options.multilingual ?? false,
 			...options
 		};
 
-		// Core functions.
-
-		// Normalize languages to an object map; if missing or invalid, use null.
+		// --- Language normalization ---
+		// Accept languages as array or object; normalize to object map.
+		// Drives multilang-core registration and sitemap-core language config.
 		const normalizedLanguages = Array.isArray(userOptions.languages)
 			? Object.fromEntries(
 					userOptions.languages
@@ -78,11 +80,14 @@ export default function baseline(options = {}) {
 		const hasLanguages = languages && Object.keys(languages).length > 0;
 		const isMultilingual = userOptions.multilingual === true && userOptions.defaultLanguage && hasLanguages;
 
+		// --- Core setup ---
+		// Global data, globals registration, static passthrough, drafts preprocessor.
 		eleventyConfig.addGlobalData('_baseline', userOptions);
 		globals(eleventyConfig);
 		eleventyConfig.addPassthroughCopy({ './src/static': '/' });
 
-		// Prevents double-registering the preprocessor, user config wins.
+		// Drafts preprocessor — skip draft pages during production builds.
+		// Guarded against double-registration; user config wins if already set.
 		if (!eleventyConfig.preprocessors.drafts) {
 			eleventyConfig.addPreprocessor('drafts', '*', (data) => {
 				if (data.draft && process.env.ELEVENTY_RUN_MODE === 'build') {
@@ -91,6 +96,10 @@ export default function baseline(options = {}) {
 			});
 		}
 
+		// --- Modules ---
+		// Registration order matters: multilang first (sets up locale data),
+		// then assets, head, sitemap. Navigator is last (debug only).
+
 		if (isMultilingual) {
 			eleventyConfig.addPlugin(modules.multilangCore, {
 				defaultLanguage: userOptions.defaultLanguage,
@@ -98,20 +107,10 @@ export default function baseline(options = {}) {
 			});
 		}
 
-		// Modules.
 		eleventyConfig.addPlugin(modules.EleventyHtmlBasePlugin, {
 			baseHref: process.env.URL || eleventyConfig.pathPrefix
 		});
-		eleventyConfig.addPlugin(modules.assetsCore);
-		eleventyConfig.addPlugin(modules.assetsPostCSS);
-		eleventyConfig.addPlugin(modules.assetsESBuild, userOptions.assets.esbuild);
-
-		if (userOptions.filterAllCollection) {
-			// Override the default collection behavior. Adding js as template format collects 11tydata.js files.
-			eleventyConfig.addCollection('all', (collectionApi) =>
-				collectionApi.getAll().filter((item) => !item.inputPath.endsWith('11tydata.js'))
-			);
-		}
+		eleventyConfig.addPlugin(modules.assetsCore, { esbuild: userOptions.assets.esbuild });
 
 		eleventyConfig.addPlugin(modules.headCore);
 		eleventyConfig.addPlugin(modules.sitemapCore, {
@@ -120,29 +119,42 @@ export default function baseline(options = {}) {
 			languages
 		});
 
-		// Filters — Module filters might move to their respective module.
+		// --- Filters ---
 		eleventyConfig.addFilter('markdownify', filters.markdownFilter);
 		eleventyConfig.addFilter('relatedPosts', filters.relatedPostsFilter);
 		eleventyConfig.addFilter('isString', filters.isStringFilter);
 
-		// Shortcodes.
+		// --- Shortcodes ---
 		eleventyConfig.addShortcode('image', shortcodes.imageShortcode);
 
-		// Add the dev server middleware for images.
+		// --- Image dev server ---
+		// Serves on-demand image transforms during `--serve` without writing to disk.
 		eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
 
-		// Debug filters and navigators.
+		// --- Debug ---
+		// Underscore-prefixed filters and navigator template for inspecting
+		// data at render time. Not part of the public API surface.
 		eleventyConfig.addFilter('_inspect', debug.inspect);
 		eleventyConfig.addFilter('_json', debug.json);
 		eleventyConfig.addFilter('_keys', debug.keys);
 		eleventyConfig.addPlugin(modules.navigatorCore, { enableNavigatorTemplate: userOptions.enableNavigatorTemplate });
+
+		// Temporary content map debug listener.
+		eleventyConfig.on('eleventy.contentMap', async ({ inputPathToUrl, urlToInputPath }) => {
+			let debuginput = inputPathToUrl;
+			let debugurl = urlToInputPath;
+
+			return (debuginput, debugurl);
+		});
 	};
 
-	// Set plugin name so `eleventyConfig.hasPlugin()` can detect it.
+	// Set a named function identity so eleventyConfig.hasPlugin() can detect this plugin.
 	Object.defineProperty(plugin, 'name', { value: `${name}` });
 	return plugin;
 }
 
+// --- Eleventy directory and template config ---
+// Exported separately so consuming sites can re-export without duplicating values.
 export const config = {
 	dir: {
 		input: 'src',

package/modules/assets-core/plugins/assets-core.js

@@ -1,7 +1,16 @@
+import path from 'node:path';
 import { TemplatePath } from '@11ty/eleventy-utils';
 import { addTrailingSlash, resolveAssetsDir } from '../../../core/helpers.js';
 import { warnIfVerbose, getVerbose } from '../../../core/logging.js';
 
+import assetsESbuild from '../../assets-esbuild/process.js';
+import assetsPostCSS from '../../assets-postcss/process.js';
+
+/**
+ * Sync the cache object with resolved directory paths.
+ * Called once at registration time and again on the eleventy.directories event
+ * when Eleventy finalizes its directory config.
+ */
 const syncCacheFromDirectories = (cache, dirs, rawDir) => {
 	const inputDir = TemplatePath.addLeadingDotSlash(dirs.input || './');
 	const outputDir = TemplatePath.addLeadingDotSlash(dirs.output || './');
@@ -13,6 +22,10 @@ const syncCacheFromDirectories = (cache, dirs, rawDir) => {
 	cache.assetsOutput = assetsOutputDir;
 };
 
+/**
+ * Guard: resolve directories from eleventyConfig.dir if the eleventy.directories
+ * event hasn't fired yet (e.g. when global data or watch targets are read early).
+ */
 const ensureCache = (cache, eleventyConfig, rawDir, verbose) => {
 	if (cache.assetsInput) return;
 	syncCacheFromDirectories(cache, eleventyConfig.dir || {}, rawDir);
@@ -22,31 +35,37 @@ const ensureCache = (cache, eleventyConfig, rawDir, verbose) => {
 /**
  * eleventy-plugin-assets-core
  *
- * Resolve assets input/output directories, register a virtual
- * `directories.assets`, expose the resolved paths via global data, and add
- * a watch target under the resolved assets input directory.
+ * The single assets plugin. Owns all Eleventy wiring for JS and CSS processing:
+ * directory resolution, template formats, extensions, compile guards, inline
+ * filters, watch targets, and global data. Processing logic lives in the
+ * pure functions imported from assets-esbuild and assets-postcss.
  *
  * Options:
  *  - verbose  (boolean, default global baseline verbose): enable verbose logs.
+ *  - esbuild  (object): options forwarded to esbuild (minify, target).
+ *    Defaults live in assets-esbuild/process.js — pass only overrides.
  */
 /** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
 export default function assetsCore(eleventyConfig, options = {}) {
 	const verbose = getVerbose(eleventyConfig) || options.verbose || false;
 	const userKey = 'assets';
 
-	// Extract raw directory value from config (can be done early)
+	// Extract raw directory value from config (can be done early).
 	const rawDir = eleventyConfig.dir?.[userKey] || userKey;
 
-	// Cache object (raw values; normalized later by syncCacheFromDirectories)
+	// Cache holds resolved paths. Initialized as nulls, populated immediately
+	// by syncCacheFromDirectories, then updated when eleventy.directories fires.
 	const cache = {
-		input: eleventyConfig.dir?.input || null,
-		output: eleventyConfig.dir?.output || null,
-		assetsInput: eleventyConfig.dir?.assets ?? userKey ?? null,
+		input: null,
+		output: null,
+		assetsInput: null,
 		assetsOutput: null
 	};
 
 	syncCacheFromDirectories(cache, eleventyConfig.dir || {}, rawDir);
 
+	// Update cache when Eleventy finalizes directories, and register a virtual
+	// `directories.assets` key so other code can read the resolved assets path.
 	eleventyConfig.on('eleventy.directories', (directories) => {
 		syncCacheFromDirectories(cache, directories, rawDir);
 
@@ -66,19 +85,113 @@ export default function assetsCore(eleventyConfig, options = {}) {
 		});
 	});
 
+	// Expose resolved assets paths as global data for templates.
+	// Templates use _baseline.assets.input to build paths for inline filters.
 	eleventyConfig.addGlobalData('_baseline.assets', () => {
 		ensureCache(cache, eleventyConfig, rawDir, verbose);
-		// Merge with existing _baseline.assets (e.g., esbuild config)
-		const existing = eleventyConfig.globalData?._baseline?.assets || {};
 		return {
 			input: cache.assetsInput,
-			output: cache.assetsOutput,
-			...existing
+			output: cache.assetsOutput
 		};
 	});
 
-	// Watch target — use resolved assets input dir.
+	// Watch common asset formats so edits trigger reloads during --serve.
 	ensureCache(cache, eleventyConfig, rawDir, verbose);
 	const watchGlob = TemplatePath.join(cache.assetsInput, '**/*.{css,js,svg,png,jpeg,jpg,webp,gif,avif}');
 	eleventyConfig.addWatchTarget(watchGlob);
+
+	// --- JS (esbuild) ---
+	// Register js as a template format. Only index.js files under assets/js/
+	// are compiled; everything else (11tydata.js, non-entry scripts) is skipped
+	// by the compile guard. The inline filter wraps the same process function.
+	// Defaults (minify, target) live in assets-esbuild/process.js.
+
+	const esbuildOptions = options.esbuild || {};
+	const jsDir = `${cache.assetsInput}js/`;
+
+	eleventyConfig.addTemplateFormats('js');
+
+	// Prevent Eleventy from processing 11tydata.js files as templates.
+	// The compile guard below also filters these, but without this ignore
+	// Eleventy still enters them into the template graph (data cascade,
+	// permalink computation) before compile gets a chance to reject them.
+	eleventyConfig.ignores.add(`${cache.input}**/*.11tydata.js`);
+
+	eleventyConfig.addExtension('js', {
+		outputFileExtension: 'js',
+		useLayouts: false,
+		read: false,
+		compileOptions: {
+			permalink: true,
+			cache: true
+		},
+		// Compile guard: only process index.js files under the assets js directory.
+		// Returning undefined skips the file without error.
+		compile: async function (_inputContent, inputPath) {
+			if (
+				inputPath.includes('11tydata.js') ||
+				!inputPath.startsWith(jsDir) ||
+				path.basename(inputPath) !== 'index.js'
+			) {
+				return;
+			}
+
+			return async () => assetsESbuild(inputPath, esbuildOptions);
+		}
+	});
+
+	// Inline filter: bundle a JS file and wrap in <script> tags.
+	// Accepts per-call esbuild options (merged with defaults in process.js).
+	// Eleventy's addAsyncFilter handles the Nunjucks callback bridge,
+	// so this is a plain async function.
+	eleventyConfig.addAsyncFilter('inlineESbuild', async function (inputPath, opts = {}) {
+		try {
+			const js = await assetsESbuild(inputPath, opts);
+			return `<script>${js}</script>`;
+		} catch {
+			// Non-fatal: return an error comment so the build doesn't break.
+			return `<script>/* Error processing JS */</script>`;
+		}
+	});
+
+	// --- CSS (PostCSS) ---
+	// Register css as a template format. Only index.css files under assets/css/
+	// are compiled; non-entry CSS is skipped. Reads from disk (read: false) —
+	// the process function owns its own I/O. Config loading and caching live
+	// in assets-postcss/process.js.
+
+	const cssDir = `${cache.assetsInput}css/`;
+
+	eleventyConfig.addTemplateFormats('css');
+
+	eleventyConfig.addExtension('css', {
+		outputFileExtension: 'css',
+		useLayouts: false,
+		read: false,
+		compileOptions: {
+			permalink: true,
+			cache: true
+		},
+		// Compile guard: only process index.css files under the assets css directory.
+		compile: async function (_inputContent, inputPath) {
+			if (!inputPath.startsWith(cssDir) || path.basename(inputPath) !== 'index.css') {
+				return;
+			}
+
+			return async () => assetsPostCSS(inputPath);
+		}
+	});
+
+	// Inline filter: process a CSS file through PostCSS and wrap in <style> tags.
+	// Eleventy's addAsyncFilter handles the Nunjucks callback bridge,
+	// so this is a plain async function.
+	eleventyConfig.addAsyncFilter('inlinePostCSS', async function (inputPath) {
+		try {
+			const css = await assetsPostCSS(inputPath);
+			return `<style>${css}</style>`;
+		} catch {
+			// Non-fatal: return an error comment so the build doesn't break.
+			return `<style>/* Error processing CSS */</style>`;
+		}
+	});
 }

package/modules/assets-esbuild/{filters/inline-esbuild.js → process.js}

@@ -2,7 +2,16 @@ import * as esbuild from 'esbuild';
 
 const defaultOptions = { minify: true, target: 'es2020' };
 
-export default async function inlineESbuild(jsFilePath, options = {}) {
+/**
+ * Bundle a JS file with esbuild.
+ *
+ * @param {string} jsFilePath - Absolute path to the entry file.
+ * @param {Object} [options] - esbuild options (merged with defaults).
+ * @param {boolean} [options.minify=true] - Minify output.
+ * @param {string} [options.target='es2020'] - esbuild target.
+ * @returns {Promise<string>} Bundled JS text, or an error comment on failure.
+ */
+export default async function assetsESbuild(jsFilePath, options = {}) {
 	const userOptions = { ...defaultOptions, ...options };
 
 	try {

package/modules/assets-postcss/fallback/postcss.config.js

@@ -8,7 +8,7 @@ const plugins = [
 	postcssImportExtGlob,
 	postcssImport,
 	postcssPresetEnv({
-		browsers: ['> 0.2% and not dead'],
+		browsers: ['baseline widely available with downstream'],
 		preserve: true
 	})
 ];

package/modules/assets-postcss/process.js

@@ -0,0 +1,49 @@
+import fs from 'fs/promises';
+import postcss from 'postcss';
+import loadPostCSSConfig from 'postcss-load-config';
+import fallbackPostCSSConfig from './fallback/postcss.config.js';
+
+// Resolve user PostCSS config from the project root (cwd), not the Eleventy input dir.
+const configRoot = process.cwd();
+let cachedConfig = null;
+
+async function getPostCSSConfig() {
+	if (cachedConfig) return cachedConfig;
+
+	try {
+		// Prefer the consuming project's PostCSS config (postcss.config.* or package.json#postcss).
+		cachedConfig = await loadPostCSSConfig({}, configRoot);
+	} catch {
+		// If none is found, fall back to the bundled Baseline config to keep builds working.
+		const { plugins, ...options } = fallbackPostCSSConfig;
+		cachedConfig = { plugins, options };
+	}
+	return cachedConfig;
+}
+
+/**
+ * Process a CSS file through PostCSS.
+ * Reads from disk, uses project postcss.config.js or bundled fallback.
+ * Config is cached for the lifetime of the process.
+ *
+ * @param {string} cssFilePath - Absolute path to the entry file.
+ * @returns {Promise<string>} Processed CSS text, or an error comment on failure.
+ */
+export default async function assetsPostCSS(cssFilePath) {
+	try {
+		const cssContent = await fs.readFile(cssFilePath, 'utf8');
+		const { plugins, options } = await getPostCSSConfig();
+
+		const result = await postcss(plugins).process(cssContent, {
+			...options,
+			from: cssFilePath
+		});
+
+		// Return raw CSS; markup wrapping is handled in the plugin registration.
+		return result.css;
+	} catch (error) {
+		console.error(error);
+		// Surface a safe CSS string so the caller can decide how to wrap it.
+		return '/* Error processing CSS */';
+	}
+}

package/modules/head-core/drivers/posthtml-head-elements.js

@@ -2,11 +2,6 @@
 // Original: https://github.com/posthtml/posthtml-head-elements
 // Adapted for Baseline head-core.
 
-// Based on posthtml-head-elements (MIT License).
-// Original: https://github.com/posthtml/posthtml-head-elements
-// Adapted for Baseline head-core.
-
-import util from 'node:util';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -22,33 +17,33 @@ function nonArray(type, content) {
 }
 
 function findElmType(type, objectData) {
-	var elementType = {
+	const elementType = {
 		meta: function () {
 			if (Array.isArray(objectData)) {
 				return nonString(type, objectData);
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a meta element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a meta element');
 			}
 		},
 		title: function () {
 			if (typeof objectData === 'string') {
 				return nonArray('title', objectData);
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a title element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a title element');
 			}
 		},
 		link: function () {
 			if (Array.isArray(objectData)) {
 				return nonString(type, objectData);
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a link element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a link element');
 			}
 		},
 		linkCanonical: function () {
 			if (Array.isArray(objectData)) {
 				return nonString('link', objectData);
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a linkCanonical element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a linkCanonical element');
 			}
 		},
 		script: function () {
@@ -58,7 +53,7 @@ function findElmType(type, objectData) {
 					return content !== undefined ? { tag: 'script', attrs, content: [content] } : { tag: 'script', attrs };
 				});
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a script element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a script element');
 			}
 		},
 		style: function () {
@@ -68,30 +63,30 @@ function findElmType(type, objectData) {
 					return content !== undefined ? { tag: 'style', attrs, content: [content] } : { tag: 'style', attrs };
 				});
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a style element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a style element');
 			}
 		},
 		base: function () {
 			if (Array.isArray(objectData)) {
 				return nonString(type, objectData);
 			} else {
-				util.log('posthtml-head-elements: Please use the correct syntax for a base element');
+				console.warn('posthtml-head-elements: Please use the correct syntax for a base element');
 			}
 		},
 		default: function () {
-			util.log('posthtml-head-elements: Please make sure the HTML head type is correct');
+			console.warn('posthtml-head-elements: Please make sure the HTML head type is correct');
 		}
 	};
 
 	if (type.indexOf('_') !== -1) {
-		type = type.substr(0, type.indexOf('_'));
+		type = type.slice(0, type.indexOf('_'));
 	}
 
 	return elementType[type]() || elementType['default']();
 }
 
 function buildNewTree(headElements, EOL) {
-	var newHeadElements = [];
+	const newHeadElements = [];
 
 	Object.keys(headElements).forEach(function (value) {
 		newHeadElements.push(findElmType(value, headElements[value]));
@@ -113,11 +108,11 @@ export default function (options) {
 	options.headElementsTag = options.headElementsTag || 'posthtml-head-elements';
 
 	if (!options.headElements) {
-		util.log(
+		console.warn(
 			"posthtml-head-elements: Don't forget to add a link to the JSON file containing the head elements to insert"
 		);
 	}
-	var jsonOne = typeof options.headElements !== 'string' ? options.headElements : require(options.headElements);
+	const jsonOne = typeof options.headElements !== 'string' ? options.headElements : require(options.headElements);
 
 	return function posthtmlHeadElements(tree) {
 		tree.match({ tag: options.headElementsTag }, function () {

package/modules/head-core/plugins/head-core.js

@@ -2,22 +2,37 @@ import headElements from '../drivers/posthtml-head-elements.js';
 import { getVerbose, logIfVerbose } from '../../../core/logging.js';
 import { buildHead } from '../utils/head-utils.js';
 
+/**
+ * eleventy-plugin-head-core
+ *
+ * Manages the <head> for every page. Merges site-level defaults, page-level
+ * overrides, and computed values (canonical URL, open graph, structured data)
+ * into a single head spec, then injects the result into HTML via a PostHTML
+ * transform. Pages control their head through a `head` data key.
+ *
+ * Depends on: core/logging, head-core/utils/head-utils, head-core/drivers/posthtml-head-elements.
+ * No cross-module dependencies.
+ */
 /** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
 export default function headCore(eleventyConfig, options = {}) {
 	const verbose = getVerbose(eleventyConfig) || options.verbose || false;
 
-	// Following options are not public.
+	// Internal options — not part of the public API.
 	const userKey = options.dirKey || 'head';
 	const headElementsTag = options.headElementsTag || 'baseline-head';
 	const eol = options.EOL || '\n';
 	const pathPrefix = options.pathPrefix ?? eleventyConfig?.pathPrefix ?? '';
 	const siteUrl = options.siteUrl;
 
+	// Cache the content map so canonical URLs can resolve inputPath → URL.
+	// Updated each build when Eleventy emits the contentMap event.
 	let cachedContentMap = {};
 	eleventyConfig.on('eleventy.contentMap', ({ inputPathToUrl, urlToInputPath }) => {
 		cachedContentMap = { inputPathToUrl, urlToInputPath };
 	});
 
+	// Computed global data: build the head spec for every page through the
+	// data cascade. Templates access the result via `page.head`.
 	eleventyConfig.addGlobalData('eleventyComputed.page.head', () => {
 		return (data) =>
 			buildHead(data, {
@@ -30,6 +45,9 @@ export default function headCore(eleventyConfig, options = {}) {
 			});
 	});
 
+	// HTML transform: inject the head spec into the document <head> using
+	// PostHTML. Replaces the <baseline-head> placeholder tag with real elements.
+	// Falls back to building the spec from context if page.head isn't available.
 	eleventyConfig.htmlTransformer.addPosthtmlPlugin('html', function (context) {
 		logIfVerbose(verbose, 'head-core: injecting head elements for', context?.page?.inputPath || context?.outputPath);