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

package/README.md

@@ -1,6 +1,14 @@
-# Eleventy Plugin Baseline
+# Eleventy Baseline
 
-An experimental Swiss army knife toolkit for Eleventy. Bundles handy helpers for assets, head/meta, navigation, sitemaps, debugging, and more — without turning into a full theme.
+_An experimental Swiss army knife for Eleventy._
+
+Eleventy Baseline is a lightweight toolkit built around a simple question:
+
+> What if Eleventy had a minimal, optional layer of conventions — just enough to eliminate repetition, but not enough to feel restrictive?
+
+It explores what a "core" for Eleventy could look like without becoming a framework or theme — small, practical tools rather than sweeping abstractions. If you've ever started a new Eleventy project and found yourself copy-pasting the same asset pipeline, the same head template, the same image shortcode for the third time, this is for you.
+
+This is a practical, evolving baseline. Things might shift, break, or get renamed as the project evolves.
 
 ## Install
 
@@ -16,6 +24,8 @@ For a fresh project (install Eleventy and eleventy-img too):
 npm install @11ty/eleventy @11ty/eleventy-img @apleasantview/eleventy-plugin-baseline
 ```
 
+Requires Eleventy 3.x and Node >=20.
+
 ## Usage
 
 In your Eleventy config (ESM):
@@ -34,13 +44,32 @@ export default function (eleventyConfig) {
 export const config = baselineConfig;
 ```
 
-Requires Eleventy 3.x.
+## What's included
+
+When the plugin loads, you get core filters, Nunjucks globals, debugging utilities, and an image shortcode (via eleventy-img) out of the box. On top of that, the plugin is organized into opt-in modules — take what you need:
+
+| Module | What it does |
+|---|---|
+| `assets-core` | Shared foundation for the asset pipeline |
+| `assets-esbuild` | JS bundling via esbuild, with an inline injection filter for critical scripts |
+| `assets-postcss` | CSS processing via PostCSS + cssnano, with an inline injection filter for critical styles |
+| `head-core` | Drop `<baseline-head>` into your template and get sensible meta, canonical, og:image, and basic SEO defaults — processed by PostHTML at build time |
+| `multilang-core` | Directory-based multilingual support: per-language collections, hreflang, sitemaps, and language normalization |
+| `navigator-core` | Navigation tree helpers and a `_navigator` Nunjucks global |
+| `sitemap-core` | XML sitemap generation with draft-page support |
 
 ## Docs
 
-Documentation tracks latest builds:  
+Full documentation — tutorials, how-to guides, and reference — lives at:
 [https://eleventy-plugin-baseline.netlify.app/](https://eleventy-plugin-baseline.netlify.app/)
 
+## Contributing
+
+Opinions, issues, and pull requests are welcome. If something doesn't work as documented, or
+you've found a pattern that fits the spirit of the project,
+[open an issue](https://github.com/apleasantview/eleventy-plugin-baseline/issues) and let's talk.
+You can also find me on [Mastodon](https://mastodon.social/@crisverstraeten).
+
 ## License
 
 MIT. See `LICENSE`.

package/core/debug.js

@@ -1,18 +1,33 @@
 import { inspect as utilInspect } from 'node:util';
 
 // Adapted from pdehaan - https://github.com/pdehaan/eleventy-plugin-debug
-const debugOptions = Object.assign({
-	space: 0
-});
+const debugOptions = { space: 0 };
 
+/**
+ * Pretty-print an object using Node's util.inspect.
+ * @param {*} obj - Value to inspect.
+ * @param {Object} [options={}] - Options forwarded to util.inspect.
+ * @returns {string}
+ */
 function inspect(obj, options = {}) {
 	return utilInspect(obj, options);
 }
 
+/**
+ * Serialize an object to JSON.
+ * @param {*} obj - Value to serialize.
+ * @param {number} [space] - Indentation level (default 0, compact).
+ * @returns {string}
+ */
 function json(obj, space = debugOptions.space) {
 	return JSON.stringify(obj, null, space);
 }
 
+/**
+ * Return an object's own keys, sorted alphabetically.
+ * @param {Object} obj
+ * @returns {string[]}
+ */
 function keys(obj) {
 	return Object.keys(obj).sort();
 }

package/core/filters/isString.js

@@ -1,3 +1,8 @@
+/**
+ * Test whether a value is a string.
+ * @param {*} object - Value to test.
+ * @returns {boolean}
+ */
 export default function isStringFilter(object) {
 	return typeof object === 'string';
 }

package/core/filters/markdown.js

@@ -3,6 +3,12 @@ import markdownit from 'markdown-it';
 
 const md = markdownit();
 
+/**
+ * Render a string as inline Markdown (no wrapping <p> tag).
+ * @param {string} string - Markdown source.
+ * @returns {string} HTML output.
+ */
 export const markdownFilter = (string) => {
+	if (!string) return '';
 	return md.renderInline(string);
 };

package/core/filters/related-posts.js

@@ -1,3 +1,9 @@
+/**
+ * Filter the current page out of a collection.
+ * Uses `this.ctx.page` from the Nunjucks runtime to identify the current page.
+ * @param {Array<Object>} [collection=[]] - Collection to filter.
+ * @returns {Array<Object>} Collection without the current page.
+ */
 export default function relatedPostsFilter(collection = []) {
 	const page = this?.ctx?.page;
 	if (!page?.url) return collection;

package/core/helpers.js

@@ -1,4 +1,3 @@
-import path from 'node:path';
 import { TemplatePath } from '@11ty/eleventy-utils';
 
 /**
@@ -14,11 +13,12 @@ export function addTrailingSlash(path) {
 }
 
 /**
- * Resolves the assets directory path from config
- * Follows Eleventy's pattern: join inputDir + rawDir, then normalize and add trailing slash
- * @param {string} inputDir - The input directory (e.g., "./src/")
- * @param {string} rawDir - Raw directory value from config (e.g., "assets")
- * @returns {{assetsDir: string, assetsDirRelative: string}}
+ * Resolves the assets directory paths from config.
+ * Joins inputDir/outputDir with rawDir, normalizes, and adds trailing slashes.
+ * @param {string} inputDir - The input directory (e.g., "./src/").
+ * @param {string} outputDir - The output directory (e.g., "./dist/").
+ * @param {string} rawDir - Raw directory value from config (e.g., "assets").
+ * @returns {{assetsDir: string, assetsOutputDir: string}}
  */
 export function resolveAssetsDir(inputDir, outputDir, rawDir) {
 	// Join input/output with assets subdir and normalize
@@ -34,94 +34,3 @@ export function resolveAssetsDir(inputDir, outputDir, rawDir) {
 	};
 }
 
-/**
- * Builds glob patterns for fast-glob (absolute paths)
- * @param {string[]} patterns - User-provided patterns
- * @param {string} assetsDir - Assets directory (relative, e.g., "./src/assets/")
- * @returns {string[]} Absolute glob patterns
- */
-export function buildGlobPatterns(patterns, assetsDir) {
-	const assetsDirAbsolute = TemplatePath.absolutePath(TemplatePath.stripLeadingDotSlash(assetsDir));
-
-	return patterns.map((pattern) => {
-		const normalized = TemplatePath.standardizeFilePath(pattern);
-		return normalized.startsWith('/') || path.isAbsolute(normalized)
-			? normalized
-			: TemplatePath.join(assetsDirAbsolute, normalized);
-	});
-}
-
-/**
- * Extracts file metadata from a file path
- * @param {string} filePath - Normalized file path
- * @returns {{basename: string, fileSlug: string, inputFileExtension: string}}
- */
-export function extractFileMetadata(filePath) {
-	const ext = path.extname(filePath); // Returns extension with dot (e.g., ".css") or ""
-	const inputFileExtension = ext && ext.length > 0 ? ext.slice(1) : '';
-	const basename = TemplatePath.getLastPathSegment(filePath, false);
-	const fileSlug = ext ? basename.slice(0, -ext.length) : basename;
-
-	return { basename, fileSlug, inputFileExtension };
-}
-
-/**
- * Creates a collection item from a relative file path
- * @param {string} inputPath - Relative path from project root (e.g., "./src/assets/css/index.css")
- * @param {string} inputDir - Input directory (e.g., "./src/")
- * @param {string} outputDir - Output directory (e.g., "./dist/")
- * @param {string} assetsDirRelative - Assets directory relative to input (e.g., "assets")
- * @param {string} passthroughOutput - Output path for passthrough
- * @param {boolean} passthrough - Whether passthrough is enabled
- * @returns {object} Collection item
- */
-export function createCollectionItem(
-	inputPath,
-	inputDir,
-	outputDir,
-	assetsDirRelative,
-	passthroughOutput,
-	passthrough
-) {
-	const { basename, fileSlug, inputFileExtension } = extractFileMetadata(inputPath);
-
-	// Get path relative to input directory
-	// e.g., inputPath = "./src/assets/css/index.css", inputDir = "./src/"
-	// relToInput = "assets/css/index.css"
-	const relToInput = TemplatePath.stripLeadingSubPath(inputPath, TemplatePath.addLeadingDotSlash(inputDir));
-
-	// outputPath: prepend output directory (with leading ./)
-	// e.g., relToInput = "assets/css/index.css", outputDir = "./dist/"
-	// outputPath = "./dist/assets/css/index.css"
-	const outputPath = TemplatePath.addLeadingDotSlash(
-		TemplatePath.normalize(TemplatePath.join(TemplatePath.addLeadingDotSlash(outputDir), relToInput))
-	);
-
-	// relToAssets: path relative to assets directory for URL generation
-	// e.g., inputPath = "./src/assets/css/index.css", assetsDirRelative = "assets"
-	// relToAssets = "css/index.css"
-	const assetsDirPath = TemplatePath.addLeadingDotSlash(TemplatePath.join(inputDir, assetsDirRelative));
-	const relToAssets = TemplatePath.stripLeadingSubPath(inputPath, assetsDirPath);
-
-	const url = passthrough ? TemplatePath.join(passthroughOutput, relToAssets).replace(/\/$/, '') : undefined;
-
-	// filePathStem: path relative to input without extension, with leading slash
-	// e.g., relToInput = "assets/css/index.css"
-	// filePathStem = "/assets/css/index"
-	const filePathStem =
-		'/' +
-		(inputFileExtension
-			? relToInput.slice(0, -inputFileExtension.length - 1) // Remove extension and dot
-			: relToInput);
-
-	return {
-		inputPath,
-		outputPath,
-		basename,
-		fileSlug,
-		inputFileExtension,
-		filePathStem,
-		dir: TemplatePath.getDirFromFilePath(inputPath),
-		url
-	};
-}

package/core/logging.js

@@ -25,8 +25,8 @@ export function logIfVerbose(verbose, message, ...args) {
  * @param {boolean} verbose - Whether verbose logging is enabled
  * @param {string} message - Warning message
  */
-export function warnIfVerbose(verbose, message) {
+export function warnIfVerbose(verbose, message, ...args) {
 	if (verbose) {
-		console.warn(`[eleventy-plugin-baseline] WARN ${message}`);
+		console.warn(`[eleventy-plugin-baseline] WARN ${message}`, ...args);
 	}
 }

package/core/modules.js

@@ -5,8 +5,6 @@ import { EleventyHtmlBasePlugin } from '@11ty/eleventy';
 import multilangCore from '../modules/multilang-core/plugins/multilang-core.js';
 import navigatorCore from '../modules/navigator-core/plugins/navigator-core.js';
 import assetsCore from '../modules/assets-core/plugins/assets-core.js';
-import assetsPostCSS from '../modules/assets-postcss/plugins/assets-postcss.js';
-import assetsESBuild from '../modules/assets-esbuild/plugins/assets-esbuild.js';
 import headCore from '../modules/head-core/plugins/head-core.js';
 import sitemapCore from '../modules/sitemap-core/plugins/sitemap-core.js';
 
@@ -15,8 +13,6 @@ export default {
 	multilangCore,
 	navigatorCore,
 	assetsCore,
-	assetsPostCSS,
-	assetsESBuild,
 	headCore,
 	sitemapCore
 };

package/core/shortcodes/image.js

@@ -1,128 +1,162 @@
-import path from 'node:path';
-import Image from '@11ty/eleventy-img';
-
-const DEFAULT_WIDTHS = [320, 640, 960, 1280];
-const DEFAULT_FORMATS = ['avif', 'webp', 'jpeg'];
-const DEFAULT_SIZES = '(max-width: 768px) 100vw, 768px';
-
-function pickRenditions(metadata) {
-	// Use the first available format; first entry is smallest, last is largest.
-	const firstFormat = Object.values(metadata)[0];
-	const lowsrc = firstFormat?.[0];
-	const highsrc = firstFormat?.[firstFormat.length - 1];
-	return { lowsrc, highsrc };
-}
-
-/**
- * Responsive image shortcode using @11ty/eleventy-img.
- *
- * @param {Object} options
- * @param {string} options.src                          Required image source (local or remote).
- * @param {string} options.alt                          Required alt text (empty string allowed for decorative).
- * @param {string} [options.caption=""]                 Optional caption; enables figure wrapper when non-empty.
- * @param {("lazy"|"eager")} [options.loading="lazy"]   Loading behavior.
- * @param {string} [options.containerClass=""]          Class applied to <picture>.
- * @param {string} [options.imageClass=""]              Class applied to <img>.
- * @param {Array<number|string>} [options.widths=DEFAULT_WIDTHS]   Widths passed to eleventy-img.
- * @param {string} [options.sizes=DEFAULT_SIZES]        Sizes attribute used on sources.
- * @param {string[]} [options.formats=DEFAULT_FORMATS]  Output formats (order matters).
- * @param {string} [options.outputDir]                  Output directory for generated assets (defaults to `./dist/media/` or `./<dir.output>/media/` when set).
- * @param {string} [options.urlPath="/media/"]          Public URL base for generated assets.
- * @param {Object} [options.attrs={}]                   Extra attributes applied to <img>; `class` merges with imageClass.
- * @param {string} [options.style]                      Inline style applied to <img> (alias for attrs.style).
- * @param {boolean} [options.figure=true]               Wrap in <figure> when caption is provided.
- * @param {boolean} [options.setDimensions=true]        When false, omit width/height on <img>.
- */
-export async function imageShortcode(options = {}) {
-	const outputBase = this?.eleventy?.directories?.output || 'dist';
-	const {
-		src,
-		alt,
-		caption = '',
-		loading = 'lazy',
-		containerClass = '',
-		imageClass = '',
-		style,
-		widths = DEFAULT_WIDTHS,
-		sizes = DEFAULT_SIZES,
-		formats = DEFAULT_FORMATS,
-		outputDir = path.join('.', outputBase, 'media'),
-		urlPath = '/media/',
-		attrs = {},
-		figure = true,
-		setDimensions = true
-	} = options;
-	const hasImageTransformPlugin = this.ctx._baseline.hasImageTransformPlugin;
-
-	if (!src) throw new Error('imageShortcode: src is required');
-	if (alt === undefined) {
-		throw new Error('imageShortcode: alt is required (use empty string for decorative images)');
-	}
-
-	const normalizedCaption = caption == null ? '' : String(caption);
-	const normalizedAlt = alt == null ? '' : String(alt);
-
-	const inputDir = this?.eleventy?.directories?.input;
-	const isRemote = /^https?:\/\//i.test(src);
-	const resolvedSrc = !isRemote && inputDir ? path.join(inputDir, src.replace(/^\//, '')) : src;
-
-	const metadata = await Image(resolvedSrc, {
-		transformOnRequest: process.env.ELEVENTY_RUN_MODE === 'serve',
-		widths: [...widths],
-		formats: [...formats],
-		outputDir,
-		urlPath,
-		filenameFormat(id, srcPath, width, format) {
-			const extension = path.extname(srcPath);
-			const name = path.basename(srcPath, extension);
-			return `${name}-${width}w.${format}`;
-		}
-	});
-
-	const { lowsrc, highsrc } = pickRenditions(metadata);
-	if (!lowsrc || !highsrc) {
-		throw new Error(`imageShortcode: no renditions produced for ${src}`);
-	}
-
-	const sourceTags = Object.values(metadata)
-		.map((formatEntries) => {
-			const type = formatEntries[0].sourceType;
-			const srcset = formatEntries.map((entry) => entry.srcset).join(', ');
-			return `<source type="${type}" srcset="${srcset}" sizes="${sizes}">`;
-		})
-		.join('\n');
-
-	const { class: attrClass, ...restAttrs } = attrs;
-	const combinedClass = [imageClass, attrClass].filter(Boolean).join(' ').trim() || undefined;
-
-	const imageAttributes = {
-		src: lowsrc.url,
-		alt: normalizedAlt,
-		loading,
-		decoding: loading === 'eager' ? 'sync' : 'async',
-		class: combinedClass,
-		style,
-		...(setDimensions ? { width: highsrc.width, height: highsrc.height } : {}),
-		...restAttrs,
-		...(hasImageTransformPlugin ? { 'eleventy:ignore': true } : {})
-	};
-
-	const imgAttrString = Object.entries(imageAttributes)
-		.filter(([, value]) => value !== undefined && value !== null && value !== '')
-		.map(([key, value]) => (value === true ? key : `${key}="${value}"`))
-		.join(' ');
-
-	const pictureClass = containerClass && containerClass.trim() ? ` class="${containerClass.trim()}"` : '';
-
-	const picture = `<picture${pictureClass}>
-	${sourceTags}
-	<img ${imgAttrString}>
-</picture>`;
-
-	if (!figure || !normalizedCaption) return picture;
-
-	return `<figure>
-	${picture}
-	<figcaption>${normalizedCaption}</figcaption>
-</figure>`;
-}
+import path from 'node:path';
+import Image from '@11ty/eleventy-img';
+
+const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
+const DEFAULT_FORMATS = ['avif', 'webp'];
+const DEFAULT_SIZES = '(max-width: 768px) 100vw, 768px';
+
+/**
+ * Pick the smallest and largest rendition from eleventy-img metadata.
+ * Uses the first available format; entries are ordered smallest → largest.
+ * @param {Object} metadata - eleventy-img metadata keyed by format.
+ * @returns {{lowsrc: Object, highsrc: Object}} Smallest and largest rendition.
+ */
+function pickRenditions(metadata) {
+	const firstFormat = Object.values(metadata)[0];
+	const lowsrc = firstFormat?.[0];
+	const highsrc = firstFormat?.[firstFormat.length - 1];
+	return { lowsrc, highsrc };
+}
+
+/**
+ * Responsive image shortcode using @11ty/eleventy-img.
+ *
+ * @param {Object} options
+ * @param {string} options.src                          Required image source (local or remote).
+ * @param {string} options.alt                          Required alt text (empty string allowed for decorative).
+ * @param {string} [options.caption=""]                 Optional caption; enables figure wrapper when non-empty.
+ * @param {("lazy"|"eager")} [options.loading="lazy"]   Loading behavior.
+ * @param {string} [options.containerClass=""]          Class applied to <picture>.
+ * @param {string} [options.imageClass=""]              Class applied to <img>.
+ * @param {Array<number|string>} [options.widths=DEFAULT_WIDTHS]   Widths passed to eleventy-img.
+ * @param {string} [options.sizes=DEFAULT_SIZES]        Sizes attribute used on sources.
+ * @param {string[]} [options.formats=DEFAULT_FORMATS]  Output formats (order matters).
+ * @param {string} [options.outputDir]                  Output directory for generated assets.
+ * @param {string} [options.urlPath="/media/"]          Public URL base for generated assets.
+ * @param {Object} [options.attrs={}]                   Extra attributes applied to <img>; `class` merges with imageClass.
+ * @param {string} [options.style]                      Inline style applied to <img>. Separate from attrs.style — if both are passed, attrs.style takes precedence via restAttrs spread.
+ * @param {boolean} [options.figure=true]               Wrap in <figure> when caption is provided.
+ * @param {boolean} [options.setDimensions=true]        When false, omit width/height on <img>.
+ */
+export async function imageShortcode(options = {}) {
+	const outputBase = this?.eleventy?.directories?.output || 'dist';
+	const {
+		src,
+		alt,
+		caption = '',
+		loading = 'lazy',
+		containerClass = '',
+		imageClass = '',
+		style,
+		widths = DEFAULT_WIDTHS,
+		sizes = DEFAULT_SIZES,
+		formats = DEFAULT_FORMATS,
+		outputDir = path.join('.', outputBase, 'media'),
+		urlPath = '/media/',
+		attrs = {},
+		figure = true,
+		setDimensions = true
+	} = options;
+	// Read from global data set during plugin init. When true, `eleventy:ignore`
+	// is added to the <img> (line 140) to prevent double-processing.
+	const hasImageTransformPlugin = this.ctx._baseline.hasImageTransformPlugin;
+
+	// --- Validation and normalization ---
+
+	if (!src) throw new Error(`imageShortcode: src is required (received ${JSON.stringify(src)})`);
+	if (alt == null) {
+		console.warn('imageShortcode: alt is required (use empty string for decorative images)');
+	}
+
+	const normalizedCaption = String(caption);
+	const normalizedAlt = alt == null ? '' : String(alt);
+
+	const inputDir = this?.eleventy?.directories?.input;
+	const isRemote = /^https?:\/\//i.test(src);
+	// Note: remote URLs rely on eleventy-img's built-in fetch — no timeout/retry control at shortcode level.
+	const resolvedSrc = !isRemote && inputDir ? path.join(inputDir, src.replace(/^\//, '')) : src;
+
+	const imageOptions = {
+		widths: [...widths],
+		formats: [...formats],
+		outputDir,
+		urlPath,
+		filenameFormat(id, srcPath, width, format) {
+			const extension = path.extname(srcPath);
+			const name = path.basename(srcPath, extension);
+			return `${name}-${id.slice(0, 6)}-${width}w.${format}`;
+		}
+	};
+
+	// --- Image processing ---
+	// In serve mode, `transformOnRequest` defers processing to first browser request
+	// for faster dev startup. If it fails, retry without it — this is an edge case
+	// but one that has bitten in practice. In build mode, errors surface immediately.
+
+	let metadata;
+	try {
+		metadata = await Image(resolvedSrc, {
+			transformOnRequest: process.env.ELEVENTY_RUN_MODE === 'serve',
+			...imageOptions
+		});
+	} catch (error) {
+		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
+			console.warn(`imageShortcode: transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			metadata = await Image(resolvedSrc, imageOptions);
+		} else {
+			throw error;
+		}
+	}
+
+	const { lowsrc, highsrc } = pickRenditions(metadata);
+	if (!lowsrc || !highsrc) {
+		throw new Error(`imageShortcode: no renditions produced for ${src}`);
+	}
+
+	// --- HTML assembly ---
+	// One <source> per format, each carrying the full srcset for that format.
+	const sourceTags = Object.values(metadata)
+		.map((formatEntries) => {
+			const type = formatEntries[0].sourceType;
+			const srcset = formatEntries.map((entry) => entry.srcset).join(', ');
+			return `<source type="${type}" srcset="${srcset}" sizes="${sizes}">`;
+		})
+		.join('\n');
+
+	// Pull `class` out of attrs so it can merge with imageClass. Remaining attrs
+	// and `eleventy:ignore` (if needed) are spread onto imageAttributes below.
+	const { class: attrClass, ...restAttrs } = attrs;
+	const combinedClass = [imageClass, attrClass].filter(Boolean).join(' ').trim() || undefined;
+
+	const imageAttributes = {
+		src: lowsrc.url,
+		alt: normalizedAlt,
+		loading,
+		decoding: loading === 'eager' ? 'sync' : 'async',
+		class: combinedClass,
+		style,
+		...(setDimensions ? { width: highsrc.width, height: highsrc.height } : {}),
+		...restAttrs,
+		...(hasImageTransformPlugin ? { 'eleventy:ignore': true } : {})
+	};
+
+	// Build the attribute string, dropping any empty/null values to keep output clean.
+	const imgAttrString = Object.entries(imageAttributes)
+		.filter(([, value]) => value !== undefined && value !== null && value !== '')
+		.map(([key, value]) => (value === true ? key : `${key}="${value}"`))
+		.join(' ');
+
+	const pictureClass = containerClass && containerClass.trim() ? ` class="${containerClass.trim()}"` : '';
+
+	const picture = `<picture${pictureClass}>
+${sourceTags}
+<img ${imgAttrString}>
+</picture>`;
+
+	if (!figure || !normalizedCaption) return picture;
+
+	return `<figure>
+${picture}
+<figcaption>${normalizedCaption}</figcaption>
+</figure>`;
+}