@apleasantview/eleventy-plugin-baseline 0.1.0-next.32 → 0.1.0-next.39

package/README.md

@@ -1,14 +1,12 @@
 # Eleventy Baseline
 
-_An experimental Swiss army knife for Eleventy._
+Baseline makes the structural decisions that Eleventy leaves open: directory layout, asset pipeline, image handling, SEO, sitemaps.
 
-Eleventy Baseline is a lightweight toolkit built around a simple question:
+If you've started a new Eleventy project and found yourself wiring up the same things for the third time, this is for you. Directory structure, template engine, image formats, meta tags, asset bundling, sitemap — decisions that are individually small but collectively slow you down. Baseline makes them together, so they fit together. You get to skip the setup and start building.
 
-> What if Eleventy had a minimal, optional layer of conventions — just enough to eliminate repetition, but not enough to feel restrictive?
+You still own your site. Baseline handles the infrastructure — the parts that have well-tested answers. Your design, your content, the things that make your site yours — those stay yours.
 
-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.
+This is a working plugin, not a finished product. Things might shift, break, or get renamed.
 
 ## Install
 
@@ -28,35 +26,62 @@ Requires Eleventy 3.x and Node >=20.
 
 ## Usage
 
-In your Eleventy config (ESM):
+Add the plugin and re-export the config. The config export sets the directory structure (`src/`, `dist/`, `_includes/`, `_data/`) so Eleventy and Baseline agree on where things live.
 
 ```js
 import baseline, { config as baselineConfig } from '@apleasantview/eleventy-plugin-baseline';
 
 export default function (eleventyConfig) {
-	eleventyConfig.addPlugin(baseline, {
-		// verbose: false,
-		// enableNavigatorTemplate: false,
-		// enableSitemapTemplate: true,
-	});
+	eleventyConfig.addPlugin(baseline());
 }
 
 export const config = baselineConfig;
 ```
 
+The plugin takes two arguments: `settings` (site identity — title, url, languages, head extras) and `options` (runtime behavior — verbose, sitemap, navigator).
+
+```js
+const settings = {
+	title: 'My Site',
+	tagline: 'Built with Baseline',
+	url: 'https://www.example.com/',
+	defaultLanguage: 'en',
+	languages: {
+		en: { title: 'My Site' },
+		nl: { title: 'Mijn Site' }
+	}
+};
+
+eleventyConfig.addPlugin(
+	baseline(settings, {
+		verbose: false, // extra logging during builds
+		sitemap: true, // XML sitemap generation
+		navigator: false // debug page for inspecting template data
+	})
+);
+```
+
 ## 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 |
+The plugin registers everything on load. No setup beyond the config above.
+
+**Core** — always active:
+
+- An image shortcode (via eleventy-img) — AVIF and WebP, responsive widths, lazy loading. Alt text is required — the build warns if you skip it.
+- Filters: `markdownify`, `relatedPosts`, `isString`
+- A date-formatting global
+- Drafts preprocessor — drafts stay out of production builds automatically
+- Static passthrough (`src/static/` → site root)
+
+**Modules** — opt-in, loaded individually:
+
+| Module      | What it does                                                                                                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assets`    | The asset pipeline. One entry point per directory (`index.css`, `index.js`). Bundles JS via esbuild and processes CSS via PostCSS. Inline filters (`inlinePostCSS`, `inlineESbuild`) for critical-path assets |
+| `head`      | `<head>` tags (charset, viewport, title, description, robots, canonical, hreflang) handled for you by dropping `<baseline-head>` in your layout                                     |
+| `multilang` | Directory-based multilingual support. Per-language collections, translation mapping, i18n filters. Wraps Eleventy's I18n plugin                                                     |
+| `navigator` | Debug tooling. Globals for inspecting template data, plus debug filters (`_inspect`, `_json`, `_keys`). Optional virtual debug page                                                 |
+| `sitemap`   | XML sitemap. Every page is included unless you exclude it. Multilingual sites get per-language sitemaps plus an index                                                               |
 
 ## Docs
 

package/core/content-map-store.js

@@ -0,0 +1,51 @@
+import { getScope, addScopeListener, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:content-map-store';
+const KEY = 'contentMap';
+
+/**
+ * Content map store (runtime substrate)
+ *
+ * Captures Eleventy's content map (emitted once per build via
+ * `eleventy.contentMap`) so late-lifecycle consumers can read it back. The
+ * store self-attaches its listener; callers create it once during plugin init.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Capture point for the content map; read by page-context for canonical
+ *   URL resolution.
+ *
+ * Lifecycle:
+ *   cascade-time   → listener writes the map when Eleventy emits it
+ *   transform-time → consumers read via get()
+ *
+ * Why this exists:
+ *   The content map is event-only; without a store, late-lifecycle consumers
+ *   have no way to read it back.
+ *
+ * Scope:
+ *   Owns capture and read of the content map.
+ *   Does not own the map's shape (Eleventy's) or how consumers use it.
+ *
+ * Data flow:
+ *   eleventy.contentMap event → registry scope → get()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{get: () => object | null, snapshot: () => object | null}}
+ */
+export function createContentMapStore(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	addScopeListener(eleventyConfig, SCOPE_NAME, 'eleventy.contentMap', 'write', (scope, data) => {
+		setEntry(scope, KEY, data);
+	});
+
+	const read = () => getEntry(scope, KEY) ?? null;
+
+	return {
+		get: read,
+		snapshot: read
+	};
+}

package/core/filters/index.js

@@ -0,0 +1,4 @@
+// Filters barrel.
+export { markdownFilter } from './markdown.js';
+export { relatedPostsFilter } from './related-posts.js';
+export { isStringFilter } from './isString.js';

package/core/filters/isString.js

@@ -1,3 +1,8 @@
-export default function isStringFilter(object) {
+/**
+ * Test whether a value is a string.
+ * @param {*} object - Value to test.
+ * @returns {boolean}
+ */
+export 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,4 +1,10 @@
-export default function relatedPostsFilter(collection = []) {
+/**
+ * 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 function relatedPostsFilter(collection = []) {
 	const page = this?.ctx?.page;
 	if (!page?.url) return collection;
 	return collection.filter((post) => post.url !== page.url);

package/core/global-functions/index.js

@@ -0,0 +1,6 @@
+import { registerDateGlobal } from './date.js';
+
+/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
+export function registerGlobals(eleventyConfig) {
+	registerDateGlobal(eleventyConfig);
+}

package/core/logging.js

@@ -1,32 +1,32 @@
-/**
- * Gets verbose flag from Eleventy global data
- * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
- * @returns {boolean}
- */
-export function getVerbose(eleventyConfig) {
-	const baselineData = eleventyConfig.globalData?._baseline;
-	return !!baselineData?.verbose;
-}
+import chalk from 'kleur';
 
 /**
- * Logs a message if verbose mode is enabled
- * @param {boolean} verbose - Whether verbose logging is enabled
- * @param {string} message - Message to log
- * @param {...any} args - Additional arguments
+ * @typedef {Object} BaselineLogger
+ * @property {(...args: unknown[]) => void} info   Verbose-only.
+ * @property {(...args: unknown[]) => void} warn   Always visible.
+ * @property {(...args: unknown[]) => void} error  Always visible.
  */
-export function logIfVerbose(verbose, message, ...args) {
-	if (verbose) {
-		console.log(`[eleventy-plugin-baseline] INFO ${message}`, ...args);
-	}
-}
 
 /**
- * Logs a warning if verbose mode is enabled
- * @param {boolean} verbose - Whether verbose logging is enabled
- * @param {string} message - Warning message
+ * Create a namespaced logger. Prefix is `[baseline]` at plugin root and
+ * `[baseline:<namespace>]` inside modules. `info` is gated behind `verbose`;
+ * `warn` and `error` always emit.
+ *
+ * @param {string | null | undefined} namespace
+ * @param {{ verbose?: boolean }} [options]
+ * @returns {BaselineLogger}
  */
-export function warnIfVerbose(verbose, message) {
-	if (verbose) {
-		console.warn(`[eleventy-plugin-baseline] WARN ${message}`);
-	}
+export function createLogger(namespace, { verbose = false } = {}) {
+	const label = namespace ? `[baseline/${namespace}]` : '[baseline]';
+	return {
+		info: (...args) => {
+			if (verbose) console.log(chalk.gray(label), ...args);
+		},
+		warn: (...args) => {
+			console.warn(chalk.yellow().bold(label), ...args);
+		},
+		error: (...args) => {
+			console.error(chalk.red().bold(label), ...args);
+		}
+	};
 }

package/core/page-context.js

@@ -0,0 +1,310 @@
+import pick from './utils/pick.js';
+import { slugify } from './utils/helpers.js';
+import { createLogger } from './logging.js';
+import { getScope, memoize, setEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:page-context';
+const COMPUTED_KEY = 'eleventyComputed._pageContext';
+
+/**
+ * Page context (runtime substrate)
+ *
+ * A normalised per-page object built once at cascade-time and cached for
+ * transform-time consumers. The shape downstream modules read instead of
+ * re-deriving from raw cascade data.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Lifecycle bridge between Eleventy's data cascade and the htmlTransformer.
+ *   Head reads it via `getByKey`; navigator snapshots it for inspection.
+ *
+ * Lifecycle:
+ *   cascade-time   → eleventyComputed._pageContext builds and caches the context
+ *   transform-time → consumers retrieve the cached context by page.url
+ *
+ * Why this exists:
+ *   Eleventy's htmlTransformer context exposes only page metadata, not the
+ *   data cascade. The cache lets transform-time consumers read the same
+ *   normalised view that cascade-time produced.
+ *
+ * Scope:
+ *   Owns the page-context shape, memoisation, key-based lookup, and snapshot.
+ *   Does not own the meaning of any field; modules consume them as they see fit.
+ *   Templates with `_internal: true` are skipped (synthetic sitemap pages, etc.).
+ *
+ * Data flow:
+ *   data cascade → buildPageContext → registry scope → head, navigator
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} coreContext - Resolved baseline core context (state, runtime, helpers).
+ */
+export function registerPageContext(eleventyConfig, coreContext) {
+	const { state, runtime, site } = coreContext;
+	const { slugIndex } = runtime;
+	const { settings, options } = state;
+
+	const log = createLogger(SCOPE_NAME, { verbose: options.verbose });
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	// Head options.
+	const separator = options.head?.titleSeparator ?? ' – ';
+	const generator = options.head?.showGenerator ?? false;
+
+	function shouldSkip(data) {
+		if (data._internal) return true;
+		if (data.page?.outputFileExtension !== 'html') return true;
+		return false;
+	}
+
+	// --- Helpers ---
+	const uniqueBy = (arr, keyFn) =>
+		Object.values(
+			(arr ?? []).reduce((acc, item) => {
+				if (!item) return acc;
+
+				const id = typeof keyFn === 'function' ? keyFn(item) : item?.[keyFn];
+
+				if (!id) {
+					acc[JSON.stringify(item)] = item;
+					return acc;
+				}
+
+				acc[id] = item;
+				return acc;
+			}, {})
+		);
+
+	// --- SEO helpers ---
+	function stripTrackingParams(urlObj) {
+		['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid'].forEach((p) =>
+			urlObj.searchParams.delete(p)
+		);
+
+		urlObj.hash = '';
+		return urlObj;
+	}
+
+	function extractFirstParagraph(data) {
+		const html = data?.content;
+		if (!html) return null;
+		const match = html.match(/<p>(.*?)<\/p>/i);
+		return match?.[1] ?? null;
+	}
+
+	function normalizeCanonical(path, siteUrl) {
+		if (!path || !siteUrl) return null;
+
+		const url = new URL(path, siteUrl);
+
+		url.hash = '';
+
+		return stripTrackingParams(url).href;
+	}
+
+	// --- Field resolver ---
+	function resolveField({ pageValue, siteValue, fallbackValue, isHome }) {
+		let value = pageValue ?? siteValue ?? fallbackValue ?? null;
+
+		return value;
+	}
+
+	// --- Builders ---
+	function buildSite(lang, userSettings) {
+		const langEntry = lang ? userSettings.languages?.[lang] : undefined;
+		return {
+			title: langEntry?.title ?? userSettings.title ?? '',
+			tagline: langEntry?.tagline ?? userSettings.tagline ?? '',
+			description: langEntry?.description ?? userSettings.description ?? '',
+			url: userSettings.url ?? '',
+			noindex: userSettings.noindex === true
+		};
+	}
+
+	function buildPage(pageInput) {
+		return {
+			inputPath: pageInput?.inputPath ?? null,
+			fileSlug: pageInput?.fileSlug ?? null,
+			filePathStem: pageInput?.filePathStem ?? null,
+			outputFileExtension: pageInput?.outputFileExtension ?? null,
+			templateSyntax: pageInput?.templateSyntax ?? null,
+			date: pageInput?.date ?? null,
+			url: pageInput?.url ?? null,
+			outputPath: pageInput?.outputPath ?? null,
+			lang: pageInput?.lang ?? null,
+			locale: pageInput?.locale ?? null,
+			sitemap: pageInput?.sitemap ?? null
+		};
+	}
+
+	function buildEntry(data) {
+		const rawSlug = data?.slug ?? data?.page?.fileSlug;
+
+		return {
+			title: data?.seo?.title ?? data?.title ?? null,
+			description: data?.seo?.description ?? data?.description ?? null,
+			excerpt: data?.excerpt ?? null,
+			slug: slugify(rawSlug),
+			head: data?.head ?? null
+		};
+	}
+
+	function buildQuery({ entry, page }) {
+		return {
+			isHome: page.url === '/'
+		};
+	}
+
+	function buildMeta({ data, site, page, query }) {
+		const noindex = site.noindex || data?.noindex === true;
+
+		const robots = noindex
+			? 'noindex, nofollow'
+			: 'index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1';
+
+		const contentMap = runtime.contentMap;
+
+		const siteTitle = site.title;
+		const siteDescription = site.description;
+		const tagline = site.tagline;
+
+		const pageTitle = data?.seo?.title ?? data?.title ?? siteTitle;
+		const pageDescription = data?.seo?.description ?? data?.description ?? data?.excerpt ?? extractFirstParagraph(data);
+
+		function enhance(value) {
+			if (query.isHome && !data?.seo?.title && tagline) {
+				return `${siteTitle}${separator}${tagline}`;
+			}
+
+			if (!query.isHome && pageTitle && siteTitle && pageTitle !== siteTitle) {
+				return `${pageTitle}${separator}${siteTitle}`;
+			}
+
+			return value;
+		}
+
+		// ---- DESCRIPTION ----
+		const description = resolveField({
+			pageValue: pageDescription,
+			siteValue: siteDescription,
+			isHome: query.isHome
+		});
+
+		// ---- TITLE ----
+		const base = resolveField({
+			pageValue: pageTitle,
+			siteValue: siteTitle
+		});
+
+		const title = enhance(base);
+
+		// ---- CANONICAL ----
+		let canonical = null;
+
+		if (!noindex) {
+			const rawCanonical =
+				data?.canonical ?? page.url ?? (page.inputPath && contentMap?.inputPathToUrl?.[page.inputPath]?.[0]);
+
+			canonical = normalizeCanonical(rawCanonical, site.url);
+		}
+
+		return {
+			title,
+			description,
+			canonical,
+			robots,
+			noindex
+		};
+	}
+
+	function buildRender(data) {
+		return {
+			generator: data?.eleventy?.generator ?? null
+		};
+	}
+
+	// HEAD (global + page-level merge + dedupe)
+	function buildHead({ userSettings, data }) {
+		const userHead = userSettings.head ?? {};
+		const pageHead = data?.head ?? {};
+
+		const link = uniqueBy([...(userHead.link ?? []), ...(pageHead.link ?? [])], (item) => {
+			if (item?.rel === 'canonical') {
+				try {
+					return normalizeCanonical(item.href, site.url);
+				} catch {
+					return item?.href;
+				}
+			}
+			return item?.href;
+		});
+
+		const script = uniqueBy([...(userHead.script ?? []), ...(pageHead.script ?? [])], 'src');
+
+		const style = uniqueBy([...(userHead.style ?? []), ...(pageHead.style ?? [])], 'href');
+
+		const meta = uniqueBy([...(userHead.meta ?? []), ...(pageHead.meta ?? [])], 'name');
+
+		return {
+			link,
+			script,
+			style,
+			meta
+		};
+	}
+
+	/**
+	 * Main context builder.
+	 * Pure transformation: Eleventy data → normalised page context.
+	 */
+	function buildPageContext(data) {
+		const pageInput = data.page ?? {};
+		const userSettings = data.settings ?? settings;
+
+		const page = buildPage(pageInput);
+		const site = buildSite(page.lang, userSettings);
+		const entry = buildEntry(data);
+		const query = buildQuery({ entry, page });
+		const meta = buildMeta({ data, site, page, query });
+		const render = buildRender(data);
+		const head = buildHead({ userSettings, data });
+
+		const context = {
+			site,
+			page,
+			entry,
+			query,
+			meta,
+			render,
+			head
+		};
+
+		const inspectionKey = context.page.url ?? context.page.inputPath;
+		if (inspectionKey) setEntry(scope, inspectionKey, context);
+
+		if (slugIndex && entry.slug && page.url) {
+			const eligible = page.locale?.isDefaultLang === true;
+			if (eligible) {
+				slugIndex.set(entry.slug, page.url, page.inputPath);
+			}
+		}
+
+		return context;
+	}
+
+	eleventyConfig.addGlobalData(COMPUTED_KEY, () => {
+		return (data) => {
+			if (shouldSkip(data)) return null;
+			return memoize(scope, data, buildPageContext);
+		};
+	});
+
+	log.info('Page context added to the data cascade and registry exposed');
+
+	return {
+		get: (data) => scope.cache.get(data),
+		getByKey: (key) => scope.values.get(key),
+		snapshot: () => Object.fromEntries(scope.values)
+	};
+}

package/core/registry.js

@@ -0,0 +1,110 @@
+/**
+ * State isolation kernel (registry)
+ *
+ * Per-config scopes that hold caches, named values, and listener dedup sets.
+ * Every store and sub-registry in the substrate borrows a scope here; no
+ * feature data lives directly inside.
+ *
+ * Architecture layer:
+ *   registry
+ *
+ * System role:
+ *   Underpins virtual-dir, content-map store, translation-map store, and the
+ *   page-context registry. The seam between eleventyConfig and any long-lived
+ *   runtime state Baseline carries.
+ *
+ * Lifecycle:
+ *   build-time     → scopes created on demand
+ *   cascade-time   → values populated by store writers
+ *   transform-time → values read by transform-time consumers
+ *
+ * Why this exists:
+ *   Eleventy has no first-class place to hang per-config singletons. A
+ *   WeakMap keyed by eleventyConfig keeps state isolated across reloads and
+ *   parallel builds without leaks, and gives every consumer a stable slot.
+ *
+ * Scope:
+ *   Owns scope creation, listener dedup, and identity-keyed memoisation.
+ *   Does not own any feature data; only the containers feature code lives in.
+ *
+ * Data flow:
+ *   eleventyConfig → scope → { cache, values, listeners } → consumer
+ */
+
+const roots = new WeakMap();
+
+/**
+ * Get or create the per-eleventyConfig root that holds all named scopes.
+ */
+function getRoot(eleventyConfig) {
+	let root = roots.get(eleventyConfig);
+	if (!root) {
+		root = new Map();
+		roots.set(eleventyConfig, root);
+	}
+	return root;
+}
+
+/**
+ * Get or create a named scope bound to an Eleventy config instance.
+ *
+ * A scope is a per-config bag of state: a cache (for identity-keyed
+ * memoisation), a values map (for named entries), and a listeners set
+ * (for deduping event hookups).
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {string} name - Scope identifier (e.g. 'page-context', 'content-store').
+ * @returns {{cache: WeakMap, values: Map, listeners: Set<string>}}
+ */
+export function getScope(eleventyConfig, name) {
+	const root = getRoot(eleventyConfig);
+
+	if (!root.has(name)) {
+		root.set(name, {
+			cache: new WeakMap(),
+			values: new Map(),
+			listeners: new Set()
+		});
+	}
+
+	return root.get(name);
+}
+
+/**
+ * Attach an Eleventy event listener once per (event, key) pair within a scope.
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {string} scopeName
+ * @param {string} eventName - Eleventy event name (e.g. 'eleventy.contentMap').
+ * @param {string} listenerKey - Stable identifier for dedup.
+ * @param {(scope: object, payload: any) => void} handler
+ */
+export function addScopeListener(eleventyConfig, scopeName, eventName, listenerKey, handler) {
+	const scope = getScope(eleventyConfig, scopeName);
+	const dedupKey = `${eventName}::${listenerKey}`;
+
+	if (scope.listeners.has(dedupKey)) return;
+	scope.listeners.add(dedupKey);
+
+	eleventyConfig.on(eventName, (payload) => handler(scope, payload));
+}
+
+/**
+ * Memoise a value in the scope's cache by object identity.
+ */
+export function memoize(scope, key, factory) {
+	if (scope.cache.has(key)) {
+		return scope.cache.get(key);
+	}
+	const value = factory(key);
+	scope.cache.set(key, value);
+	return value;
+}
+
+export function setEntry(scope, name, value) {
+	scope.values.set(name, value);
+}
+
+export function getEntry(scope, name) {
+	return scope.values.get(name);
+}