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

package/core/wikilinks.js

@@ -0,0 +1,152 @@
+import { slugify } from './utils/helpers.js';
+
+/**
+ * Wikilinks (runtime substrate)
+ *
+ * MediaWiki-style inline link syntax for body markdown. Recognises
+ * [[slug]], [[slug#anchor]], [[slug:lang]], [[slug|alias]], and any
+ * combination. Resolves slugs against the slug index and, when a lang
+ * suffix is given, hops to the requested translation. Misses render as
+ * the original literal text.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Markdown-it plugin registered by the composition root via
+ *   amendLibrary('md', ...). Reads the slug index, page-context registry,
+ *   and translation-map store; writes nothing back.
+ *
+ * Lifecycle:
+ *   transform-time → parses [[...]] in body markdown and emits link or
+ *                    text tokens
+ *
+ * Why this exists:
+ *   Markdown-it has no wiki-link syntax. Eleventy resolves all
+ *   eleventyComputed values before any body renders, so the slug index
+ *   and translation map are complete by the time this rule fires.
+ *   Resolution is deterministic without a two-pass build.
+ *
+ * Scope:
+ *   Owns syntax parsing, slug-to-href resolution, the lang hop, and link
+ *   rendering with class/lang/hreflang attributes.
+ *   Does not own slug derivation (page-context), index population, or the
+ *   translation-map shape (multilang module).
+ *
+ * Data flow:
+ *   markdown-it inline state → slug index + page context + translation map → link tokens
+ *
+ * @param {import('markdown-it').default} md
+ * @param {Object} deps
+ * @param {{getBySlug: (slug: string) => string | null}} deps.slugIndex
+ * @param {{getByKey: (url: string) => any}} deps.pageContextRegistry
+ * @param {{get: () => Record<string, Record<string, {url: string, title?: string}>> | null}} [deps.translationMapStore]
+ */
+export function wikilinks(md, { slugIndex, pageContextRegistry, translationMapStore } = {}) {
+	if (!slugIndex || !pageContextRegistry) {
+		throw new Error('wikilinks plugin requires { slugIndex, pageContextRegistry }');
+	}
+
+	function parse(inner) {
+		// [[target|alias]]
+		const pipeIdx = inner.indexOf('|');
+		const target = pipeIdx === -1 ? inner : inner.slice(0, pipeIdx);
+		const alias = pipeIdx === -1 ? null : inner.slice(pipeIdx + 1).trim() || null;
+
+		// [[slug-or-langed#anchor]]
+		const hashIdx = target.indexOf('#');
+		const slugAndLang = hashIdx === -1 ? target : target.slice(0, hashIdx);
+		const rawAnchor = hashIdx === -1 ? null : target.slice(hashIdx + 1).trim() || null;
+		const anchor = rawAnchor ? slugify(rawAnchor) : null;
+
+		// [[slug:lang]]
+		const colonIdx = slugAndLang.indexOf(':');
+		const rawSlug = colonIdx === -1 ? slugAndLang : slugAndLang.slice(0, colonIdx);
+		const rawLang = colonIdx === -1 ? null : slugAndLang.slice(colonIdx + 1).trim() || null;
+
+		return { rawSlug: rawSlug.trim(), rawLang, anchor, alias };
+	}
+
+	function resolve({ rawSlug, rawLang, anchor, alias }) {
+		const slug = slugify(rawSlug);
+		if (!slug) return null;
+
+		const url = slugIndex.getBySlug(slug);
+		if (!url) return null;
+
+		const ctx = pageContextRegistry.getByKey(url);
+		const defaultTitle = ctx?.entry?.title ?? rawSlug;
+
+		const withAnchor = (u) => (anchor ? `${u}#${anchor}` : u);
+
+		if (!rawLang) {
+			return {
+				href: withAnchor(url),
+				label: alias ?? defaultTitle,
+				lang: null
+			};
+		}
+
+		const lang = rawLang.toLowerCase();
+		const translationKey = ctx?.page?.locale?.translationKey;
+		if (!translationKey) return null;
+
+		const map = translationMapStore?.get?.();
+		const entry = map?.[translationKey]?.[lang];
+		if (!entry) return null;
+
+		return {
+			href: withAnchor(entry.url),
+			label: alias ?? entry.title ?? defaultTitle,
+			lang
+		};
+	}
+
+	function tokenize(state, silent) {
+		const start = state.pos;
+		const src = state.src;
+
+		if (src.charCodeAt(start) !== 0x5b /* [ */) return false;
+		if (src.charCodeAt(start + 1) !== 0x5b) return false;
+
+		const end = src.indexOf(']]', start + 2);
+		if (end === -1) return false;
+
+		const inner = src.slice(start + 2, end);
+		// Reject nested brackets to keep the rule unambiguous.
+		if (inner.includes('[') || inner.includes(']')) return false;
+
+		if (silent) {
+			state.pos = end + 2;
+			return true;
+		}
+
+		const literal = src.slice(start, end + 2);
+		const parsed = parse(inner);
+		const result = resolve(parsed);
+
+		if (!result) {
+			const t = state.push('text', '', 0);
+			t.content = literal;
+		} else {
+			const open = state.push('link_open', 'a', 1);
+			const attrs = [
+				['href', result.href],
+				['class', 'wikilink']
+			];
+			if (result.lang) {
+				attrs.push(['lang', result.lang]);
+				attrs.push(['hreflang', result.lang]);
+			}
+			open.attrs = attrs;
+			const text = state.push('text', '', 0);
+			text.content = result.label;
+			state.push('link_close', 'a', -1);
+		}
+
+		state.pos = end + 2;
+		return true;
+	}
+
+	md.inline.ruler.before('link', 'wikilink', tokenize);
+}

package/index.js

@@ -0,0 +1,364 @@
+import 'dotenv/config';
+import { createRequire } from 'node:module';
+
+import { HtmlBasePlugin } from '@11ty/eleventy';
+import { eleventyImageOnRequestDuringServePlugin } from '@11ty/eleventy-img';
+
+import { createLogger } from './core/logging.js';
+import { createContentMapStore } from './core/content-map-store.js';
+import { createTranslationMapStore } from './core/translation-map-store.js';
+import { createSlugIndex } from './core/slug-index.js';
+import { registerVirtualDir } from './core/virtual-dir.js';
+import { registerPageContext } from './core/page-context.js';
+import { wikilinks } from './core/wikilinks.js';
+import { settingsSchema } from './core/schema.js';
+
+import { registerGlobals } from './core/global-functions/index.js';
+import { markdownFilter, relatedPostsFilter, isStringFilter } from './core/filters/index.js';
+import { imageShortcode } from './core/shortcodes/index.js';
+import { assetsCore, headCore, multilangCore, navigatorCore, sitemapCore } from './modules.js';
+
+const __require = createRequire(import.meta.url);
+const { name, version } = __require('./package.json');
+
+const mode = process.env.ELEVENTY_ENV;
+const isDev = mode === 'development';
+const isProd = mode === 'production';
+
+const LEGACY_OPTION_KEYS = [
+	'verbose',
+	'enableNavigatorTemplate',
+	'enableSitemapTemplate',
+	'assetsESBuild',
+	'multilingual'
+];
+
+// Whitelist of reserved global data keys used internally across the plugin.
+// Positive side effect is they all get listed in order and merge data to the same key.
+// Also prevents name collision with filters.
+const INTERNAL_KEYS = [
+	'_baseline',
+	'_assets',
+	'_head',
+	'_multilang',
+	'_navigator',
+	'_sitemap',
+	'_snapshot',
+	'_pageContext'
+];
+
+/**
+ * Detect legacy single-object plugin invocation.
+ *
+ * The original plugin API accepted a single merged configuration object.
+ * This helper detects that shape and enables safe normalization into
+ * the current (settings, options) contract.
+ *
+ * NOTE: arguments.length is required because default parameters mask arity.
+ */
+function looksLikeLegacyOptions(firstArg, argsLength) {
+	if (argsLength >= 2) return false;
+	if (!firstArg || typeof firstArg !== 'object') return false;
+	return LEGACY_OPTION_KEYS.some((key) => key in firstArg);
+}
+
+/**
+ * Normalize legacy plugin input into the current structured contract.
+ *
+ * - settings → site identity (content + SEO concerns)
+ * - options  → runtime behavior flags
+ */
+function splitLegacyOptions(legacy) {
+	const { defaultLanguage, languages, ...rest } = legacy;
+	return {
+		settings: { defaultLanguage, languages },
+		options: rest
+	};
+}
+
+/**
+ * Baseline (composition root)
+ *
+ * Eleventy plugin entry point. Normalises user input, builds the runtime
+ * substrate (stores + page-context registry), and registers feature modules
+ * in deterministic order.
+ *
+ * Architecture layer:
+ *   composition root
+ *
+ * System role:
+ *   The single place that wires settings + options into state, attaches
+ *   lifecycle stores, registers the page-context registry, and hands a
+ *   uniform module context to each module. No feature behaviour lives here.
+ *
+ * Lifecycle:
+ *   build-time → legacy-shape detection, state computation, virtual dir
+ *                registration, store and page-context registration, module
+ *                wiring
+ *
+ * Why this exists:
+ *   Modules need a stable, normalised input contract and a shared runtime
+ *   surface. Centralising the wiring keeps activation rules, option
+ *   inference, and registration order in one auditable place.
+ *
+ * Scope:
+ *   Owns the legacy-shape compatibility shim, state computation, runtime
+ *   store creation, page-context registration, and the module registry.
+ *   Does not own any feature behaviour; modules implement that.
+ *
+ * Data flow:
+ *   settings + options → state → runtime stores + page-context registry →
+ *   modules
+ *
+ * Typedefs (BaselineSettings, BaselineOptions, BaselineState, BaselineContext)
+ * live in core/types.js.
+ *
+ * @param {import('./core/types.js').BaselineSettings} [settings]
+ * @param {import('./core/types.js').BaselineOptions} [options]
+ */
+export default function baseline(settings = {}, options = {}) {
+	// --- Legacy compatibility layer ---
+	const argsLength = arguments.length;
+	const wasLegacy = looksLikeLegacyOptions(settings, argsLength);
+
+	if (wasLegacy) {
+		const split = splitLegacyOptions(settings);
+		settings = split.settings;
+		options = split.options;
+	}
+
+	// Base logger outputs regardless of options.
+	const baseLog = createLogger(null, { verbose: true });
+
+	// Scoped logging.
+	function scopedLog(name) {
+		return createLogger(name, { verbose: options.verbose });
+	}
+
+	if (wasLegacy) {
+		baseLog.info('DEPRECATED: single-object plugin arg. Use baseline(settings, options) instead.');
+	}
+
+	// Validate configuration shape (non-fatal).
+	const parsed = settingsSchema.safeParse(settings);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			baseLog.info('settings:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	baseLog.info('Eleventy Baseline', version);
+
+	/**
+	 * Eleventy plugin initializer.
+	 *
+	 * This function is executed during Eleventy configuration time and
+	 * composes global APIs, filters, shortcodes, and feature modules.
+	 */
+	const plugin = async function (eleventyConfig) {
+		// --- Eleventy compatibility check ---
+		try {
+			eleventyConfig.versionCheck('>=3.0');
+		} catch (e) {
+			baseLog.error('Eleventy version mismatch:', e.message);
+		}
+
+		INTERNAL_KEYS.forEach((key) => {
+			eleventyConfig.addGlobalData(key, {});
+		});
+
+		const env = {
+			name: 'Eleventy Baseline',
+			package: name,
+			version,
+			mode
+		};
+
+		eleventyConfig.addGlobalData('_baseline', {
+			env
+		});
+
+		if (!settings.url) {
+			baseLog.warn('settings.url missing — canonical URLs will be relative');
+		}
+
+		registerGlobals(eleventyConfig);
+
+		eleventyConfig.addPlugin(HtmlBasePlugin, {
+			baseHref: process.env.URL || eleventyConfig.pathPrefix
+		});
+
+		// --- State layer (authoritative configuration) ---
+		const hasImageTransformPlugin = eleventyConfig.hasPlugin('eleventyImageTransformPlugin');
+
+		const state = {
+			settings: {
+				title: settings.title,
+				tagline: settings.tagline,
+				url: settings.url,
+				noindex: settings.noindex ?? false,
+				defaultLanguage: settings.defaultLanguage,
+				languages: settings.languages,
+				head: settings.head
+			},
+
+			options: {
+				verbose: options.verbose ?? false,
+				multilang: options.multilingual ?? false,
+				sitemap: options.sitemap ?? options.enableSitemapTemplate ?? true,
+				navigator: options.navigator ?? options.enableNavigatorTemplate ?? isDev,
+				head: {
+					titleSeparator: options.head?.titleSeparator,
+					showGenerator: options.head?.showGenerator
+				},
+				assets: {
+					esbuild: options.assets?.esbuild ?? options.assetsESBuild ?? {}
+				}
+			}
+		};
+
+		eleventyConfig.addGlobalData('_baseline', {
+			features: {
+				...state.options,
+				hasImageTransformPlugin
+			}
+		});
+
+		// --- Virtual directories ---
+		registerVirtualDir(eleventyConfig, {
+			key: 'assets'
+		});
+
+		const publicDir = registerVirtualDir(eleventyConfig, {
+			key: 'public',
+			outputDir: ''
+		});
+
+		const directories = {
+			input: eleventyConfig.directories?.input,
+			output: eleventyConfig.directories?.output,
+			includes: eleventyConfig.directories?.includes,
+			data: eleventyConfig.directories?.data,
+			assets: eleventyConfig.directories?.assets,
+			public: eleventyConfig.directories?.public
+		};
+
+		eleventyConfig.addPassthroughCopy({ [publicDir.input]: '/' });
+
+		// Add paths to global.
+		eleventyConfig.addGlobalData('_baseline', {
+			paths: {
+				...directories
+			}
+		});
+
+		// --- Draft filtering (build-time concern) ---
+		if (!eleventyConfig.preprocessors.drafts) {
+			eleventyConfig.addPreprocessor('drafts', '*', (data) => {
+				if (data.draft && process.env.ELEVENTY_RUN_MODE === 'build') {
+					return false;
+				}
+			});
+		}
+
+		// --- Runtime stores (self-attach their lifecycle listeners) ---
+		const contentMapStore = createContentMapStore(eleventyConfig);
+		const translationMapStore = createTranslationMapStore(eleventyConfig);
+		const slugIndex = createSlugIndex(eleventyConfig);
+
+		// --- Module helpers (derived state) ---
+		const helpers = {};
+
+		// --- Core context (lazy access layer) ---
+		const coreContext = {
+			env,
+			state,
+			runtime: {
+				get contentMap() {
+					return contentMapStore.get();
+				},
+				translationMap: translationMapStore,
+				slugIndex
+			},
+			directories,
+			helpers
+		};
+
+		// Page context registry
+		const pageContextRegistry = registerPageContext(eleventyConfig, coreContext);
+
+		// Wikilinks: [[slug]] / [[slug | lang]] in body markdown.
+		eleventyConfig.amendLibrary('md', (md) => {
+			md.use(wikilinks, { slugIndex, pageContextRegistry, translationMapStore });
+		});
+
+		coreContext.snapshots = {
+			contentMap: () => contentMapStore.snapshot(),
+			pageContext: () => pageContextRegistry.snapshot()
+		};
+
+		// --- Module activation ---
+		const features = {
+			multilang: Boolean(state.options.multilang),
+			sitemap: Boolean(state.options.sitemap),
+			navigator: Boolean(state.options.navigator),
+			head: true,
+			assets: true
+		};
+
+		// --- Module registry ---
+		const moduleRegistry = [
+			{ when: features.multilang, name: 'multilang', plugin: multilangCore },
+			{ when: features.sitemap, name: 'sitemap', plugin: sitemapCore },
+			{ name: 'navigator', plugin: navigatorCore },
+			{ when: features.head, name: 'head', plugin: headCore, consumes: { pageContext: true } },
+			{ when: features.assets, name: 'assets', plugin: assetsCore }
+		];
+
+		for (const entry of moduleRegistry) {
+			const { when = true, name, plugin, consumes = {} } = entry;
+			if (!when) continue;
+			const moduleContext = {
+				...coreContext,
+				log: scopedLog(name),
+				resolvePageContext: consumes.pageContext ? pageContextRegistry : null
+			};
+
+			eleventyConfig.addPlugin(plugin, moduleContext);
+		}
+
+		// --- Filters ---
+		eleventyConfig.addFilter('markdownify', markdownFilter);
+		eleventyConfig.addFilter('relatedPosts', relatedPostsFilter);
+		eleventyConfig.addFilter('isString', isStringFilter);
+
+		// --- Shortcodes ---
+		eleventyConfig.addShortcode('image', imageShortcode);
+
+		// --- Dev image pipeline ---
+		eleventyConfig.addPlugin(eleventyImageOnRequestDuringServePlugin);
+	};
+
+	// Set a named function identity so eleventyConfig.hasPlugin() can detect this plugin.
+	Object.defineProperty(plugin, 'name', { value: name });
+	return plugin;
+}
+
+/**
+ * Eleventy directory configuration (external contract)
+ *
+ * Defines input/output structure for the build system.
+ */
+export const config = {
+	dir: {
+		input: 'src',
+		output: 'dist',
+		data: '_data',
+		includes: '_includes',
+		assets: 'assets',
+		public: 'static'
+	},
+	htmlTemplateEngine: 'njk',
+	markdownTemplateEngine: 'njk',
+	templateFormats: ['html', 'njk', 'md']
+};

package/modules/assets/index.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import { TemplatePath } from '@11ty/eleventy-utils';
+
+import { optionsSchema } from './schema.js';
+import assetsESbuild from './processors/esbuild-process.js';
+import assetsPostCSS from './processors/postcss-process.js';
+
+/**
+ * Assets (module)
+ *
+ * Asset pipeline integration. Wires Eleventy’s template formats to esbuild
+ * and PostCSS through compile guards that allow only declared entrypoints,
+ * and exposes inline filters for critical-path assets.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Bridge between Eleventy’s template system and the external asset
+ *   processors. Reads `directories.assets` from the virtual-dir substrate.
+ *
+ * Lifecycle:
+ *   build-time → register js/css formats, compile guards, watch target, and
+ *                inline filters; guards run per-entrypoint during compile
+ *
+ * Why this exists:
+ *   Eleventy treats every .js and .css file as a template. Without compile
+ *   guards, 11tydata.js files and non-entry assets would either pollute the
+ *   template graph or trigger the wrong processor.
+ *
+ * Scope:
+ *   Owns template format registration, compile guards, watch wiring, and the
+ *   inline filters (inlinePostCSS, inlineESbuild).
+ *   Does not own the processors themselves (assets/processors/) or
+ *   `directories.assets` resolution (core/virtual-dir.js).
+ *
+ * Data flow:
+ *   assets/{js,css}/index.{js,css} entrypoints → compile guard →
+ *   esbuild/PostCSS processor → output
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} moduleContext
+ */
+export function assetsCore(eleventyConfig, moduleContext) {
+	const { state, directories, log } = moduleContext;
+	const { settings, options } = state;
+
+	// Structural-only options check: log on mismatch, do not throw.
+	const parsed = optionsSchema.safeParse(options.assets);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	const inputDirectory = directories.input;
+	const assetsDirectory = directories.assets;
+	const jsDirectory = `${assetsDirectory}js/`;
+	const cssDirectory = `${assetsDirectory}css/`;
+
+	const esbuildOptions = options.assets.esbuild || {};
+	const dataFiles = `${inputDirectory}**/*.11tydata.js`;
+	const watchGlob = TemplatePath.join(assetsDirectory, '**/*.{css,js,svg,png,jpeg,jpg,webp,gif,avif}');
+
+	if (!assetsDirectory) {
+		log.warn('eleventyConfig.directories.assets is unset; registerVirtualDir must run before this plugin.');
+		return;
+	}
+
+	// Watch common asset formats so edits trigger reloads during --serve.
+	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.
+
+	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(dataFiles);
+
+	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(jsDirectory) ||
+				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.
+
+	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(cssDirectory) || 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>`;
+		}
+	});
+}