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

package/core/schema.js

@@ -0,0 +1,37 @@
+import * as z from 'zod';
+
+export const configSchema = z.object({
+	dir: z.object({
+		input: z.string().min(1),
+		output: z.string().min(1),
+		data: z.string().min(1),
+		includes: z.string().min(1),
+		assets: z.string().min(1),
+		public: z.string().min(1)
+	}),
+	htmlTemplateEngine: z.string().min(1),
+	markdownTemplateEngine: z.string().min(1),
+	templateFormats: z
+		.array(z.string().min(1))
+		.min(1)
+		.refine((templateFormats) => templateFormats.includes('njk'), {
+			error: 'Baseline requires njk in templateFormats'
+		})
+});
+
+export const settingsSchema = z.object({
+	title: z.string().optional(),
+	tagline: z.string().optional(),
+	url: z.string().optional(),
+	noindex: z.boolean().optional(),
+	defaultLanguage: z.string().optional(),
+	languages: z.record(z.string(), z.looseObject({})).optional(),
+	head: z
+		.object({
+			link: z.array(z.looseObject({})).optional(),
+			script: z.array(z.looseObject({})).optional(),
+			meta: z.array(z.looseObject({})).optional(),
+			style: z.array(z.looseObject({})).optional()
+		})
+		.optional()
+});

package/core/shortcodes/image.js

@@ -1,5 +1,10 @@
 import path from 'node:path';
 import Image from '@11ty/eleventy-img';
+import { createLogger } from '../logging.js';
+
+// Module-level logger. Image shortcode only uses `.warn`, which emits regardless
+// of verbose, so we don't thread verbose through the shortcode signature.
+const log = createLogger('image');
 
 const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
 const DEFAULT_FORMATS = ['avif', 'webp'];
@@ -59,13 +64,13 @@ export async function imageShortcode(options = {}) {
 	} = 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;
+	const hasImageTransformPlugin = this.ctx._baseline.features.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)');
+		log.warn('alt is required (use empty string for decorative images)');
 	}
 
 	const normalizedCaption = String(caption);
@@ -101,7 +106,7 @@ export async function imageShortcode(options = {}) {
 		});
 	} catch (error) {
 		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
-			console.warn(`imageShortcode: transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			log.warn(`transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
 			metadata = await Image(resolvedSrc, imageOptions);
 		} else {
 			throw error;

package/core/shortcodes/index.js

@@ -0,0 +1,2 @@
+// Shortcodes barrel.
+export { imageShortcode } from './image.js';

package/core/slug-index.js

@@ -0,0 +1,61 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:slug-index';
+
+/**
+ * Slug index (runtime substrate)
+ *
+ * Maps wikilink-friendly slugs to canonical page URLs. Populated by the
+ * page-context builder as each page resolves; read by the wikilinks
+ * markdown-it plugin during body render.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Forward-link index for the wikilinks plugin. In multilingual sites
+ *   only defaultLanguage pages register; the wikilinks plugin uses the
+ *   translation map to hop to other languages.
+ *
+ * Lifecycle:
+ *   cascade-time   → page-context registers slugs as templates compute
+ *   transform-time → wikilinks plugin resolves slugs during body render
+ *
+ * Why this exists:
+ *   Eleventy's data cascade resolves all eleventyComputed values before any
+ *   body renders, so the index is complete by the time wikilinks need it.
+ *   A dedicated scope keeps slug→url out of the page-context values map
+ *   (which holds url→pageContext).
+ *
+ * Scope:
+ *   Owns slug registration with collision detection and slug-keyed lookup.
+ *   Does not own slug derivation (page-context) or link rendering (wikilinks).
+ *
+ * Data flow:
+ *   page-context.buildPageContext → set() → registry scope → wikilinks getBySlug()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | null, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
+ */
+export function createSlugIndex(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set(slug, url, inputPath) {
+			if (!slug || !url) return;
+			const existing = getEntry(scope, slug);
+			if (existing && existing.url !== url) {
+				throw new Error(
+					`Wikilink slug collision: "${slug}" used by both ${existing.inputPath ?? existing.url} and ${inputPath ?? url}`
+				);
+			}
+			setEntry(scope, slug, { url, inputPath });
+		},
+		getBySlug(slug) {
+			return getEntry(scope, slug)?.url ?? null;
+		},
+		snapshot() {
+			return Object.fromEntries(scope.values);
+		}
+	};
+}

package/core/translation-map-store.js

@@ -0,0 +1,46 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:translation-map-store';
+const KEY = 'translationMap';
+
+/**
+ * Translation map store (runtime substrate)
+ *
+ * Hand-off point for the translations map: written by multilang at
+ * cascade-time, read by head at transform-time.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Bridge between the multilang module (writer) and the head module (reader).
+ *   The set/get pair lives in a registry scope rather than the data cascade
+ *   because head's PostHTML plugin runs outside the cascade.
+ *
+ * Lifecycle:
+ *   cascade-time   → multilang's translationsMap collection writes via set()
+ *   transform-time → head reads via get() to build hreflang alternates
+ *
+ * Why this exists:
+ *   The translations map is built inside an Eleventy collection, but head
+ *   needs it inside an htmlTransformer plugin where collections aren't
+ *   available.
+ *
+ * Scope:
+ *   Owns set/get on a per-config scope.
+ *   Does not own the map's shape, how it's built, or how head uses it.
+ *
+ * Data flow:
+ *   multilang translationsMap collection → set() → registry scope → head get()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{set: (map: object) => void, get: () => object | null}}
+ */
+export function createTranslationMapStore(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set: (map) => setEntry(scope, KEY, map),
+		get: () => getEntry(scope, KEY) ?? null
+	};
+}

package/core/types.js

@@ -0,0 +1,73 @@
+/**
+ * Baseline shared typedefs.
+ *
+ * Extracted from the composition root so file-level headers stay scannable.
+ * No runtime exports; this file exists for IDE and JSDoc tooling only.
+ */
+
+/**
+ * @typedef {Object} BaselineSettings
+ * Site identity and SEO configuration.
+ *
+ * @property {string} [title]
+ * @property {string} [tagline]
+ * @property {string} [url]
+ * @property {boolean} [noindex]
+ * @property {string} [defaultLanguage]
+ * @property {Record<string, unknown>} [languages]
+ * @property {Object} [head]
+ */
+
+/**
+ * @typedef {Object} BaselineOptions
+ * Runtime feature flags and behaviour configuration.
+ *
+ * User-facing input. Each module reads its own slice from `state.options.<module>`.
+ *
+ * @property {boolean} [verbose]
+ * Enables structured debug logging across modules.
+ *
+ * @property {boolean} [multilingual]
+ * Enables multilingual mode. Requires settings.defaultLanguage and
+ * settings.languages; the multilang module bails with a log otherwise.
+ *
+ * @property {boolean} [sitemap]
+ * Enables sitemap generation module (default: true).
+ *
+ * @property {boolean | { template?: boolean, inspectorDepth?: number }} [navigator]
+ * Controls navigator tooling. Boolean shorthand activates the module and
+ * the virtual debug page. Object form lets the page render flag and the
+ * inspector depth be tuned independently. Defaults to true in dev mode.
+ *
+ * @property {{ titleSeparator?: string, showGenerator?: boolean }} [head]
+ * Head module options.
+ *
+ * @property {{ esbuild?: { minify?: boolean, target?: string } }} [assets]
+ * Assets module options. The esbuild slice is permissive — any esbuild
+ * option is accepted; only `minify` and `target` are typed.
+ */
+
+/**
+ * @typedef {Object} BaselineState
+ * Fully resolved internal plugin state.
+ *
+ * @property {Object} settings
+ * @property {Object} options
+ */
+
+/**
+ * @typedef {Object} BaselineContext
+ * Shared module boundary contract.
+ *
+ * This context is the only supported interface between:
+ * - Eleventy configuration runtime
+ * - baseline core
+ * - feature modules
+ *
+ * @property {BaselineState} state
+ * @property {Object} runtime
+ * @property {Object} runtime.contentMap
+ * @property {Object} runtime.site
+ */
+
+export {};

package/core/utils/helpers.js

@@ -0,0 +1,75 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import slugifyLib from 'slugify';
+
+/**
+ * Helper function to add trailing slash to a path
+ * @param {string} path
+ * @returns {string}
+ */
+export function addTrailingSlash(path) {
+	if (path.slice(-1) === '/') {
+		return path;
+	}
+	return path + '/';
+}
+
+/**
+ * Resolve a subdirectory under input and output.
+ * Joins inputDir/outputDir with rawDir, normalises, 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 subdirectory value (e.g., "assets", "static").
+ * @returns {{input: string, output: string}}
+ */
+export function resolveSubdir(inputDir, outputDir, rawDir) {
+	const joinedInput = TemplatePath.join(inputDir, rawDir || '');
+	const joinedOutput = TemplatePath.join(outputDir, rawDir || '');
+
+	return {
+		input: addTrailingSlash(TemplatePath.standardizeFilePath(joinedInput)),
+		output: addTrailingSlash(TemplatePath.standardizeFilePath(joinedOutput))
+	};
+}
+
+/**
+ * Slugify a string into a wikilink-friendly key.
+ * Lowercases, strips diacritics, replaces non-alphanumerics with hyphens,
+ * trims leading/trailing hyphens. Returns null for empty input.
+ *
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function slugify(input) {
+	if (input == null) return null;
+	const slug = slugifyLib(String(input), { lower: true, strict: true, trim: true });
+	return slug || null;
+}
+
+/**
+ * Normalize language input to an object map.
+ * Accepts an array of language codes or an object keyed by language code.
+ * Returns null if input is invalid or empty.
+ *
+ * @param {Object} settings - Options object containing languages.
+ * @param {import('../logging.js').BaselineLogger} [logger] - Logger for dropped-entry notice.
+ * @returns {Record<string, Object>|null} Normalized language map, or null.
+ */
+export function normalizeLanguages(settings, logger) {
+	const normalizedLanguages = Array.isArray(settings.languages)
+		? Object.fromEntries(
+				settings.languages
+					.filter((lang) => typeof lang === 'string' && lang.trim())
+					.map((lang) => [lang.toLowerCase().trim(), {}])
+			)
+		: settings.languages && typeof settings.languages === 'object'
+			? settings.languages
+			: null;
+
+	if (logger && Array.isArray(settings.languages)) {
+		const normalizedCount = normalizedLanguages ? Object.keys(normalizedLanguages).length : 0;
+		if (normalizedCount !== settings.languages.length) {
+			logger.info('Some languages entries were invalid and were dropped.');
+		}
+	}
+	return normalizedLanguages;
+}

package/core/utils/pick.js

@@ -0,0 +1,7 @@
+/**
+ * Return the first value that is neither undefined nor null.
+ * @param {...*} values
+ * @returns {*}
+ */
+const pick = (...values) => values.find((v) => v !== undefined && v !== null);
+export default pick;

package/core/virtual-dir.js

@@ -0,0 +1,111 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import { resolveSubdir } from './utils/helpers.js';
+import { createLogger } from './logging.js';
+import { getScope, addScopeListener, setEntry } from './registry.js';
+
+/**
+ * Virtual directories (runtime substrate)
+ *
+ * Synthesises extra keys on eleventyConfig.directories (e.g. `assets`,
+ * `public`) that Eleventy itself won't accept, and keeps them in sync once
+ * Eleventy finalises its real directory map.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Adds virtual dir keys consumed by modules (assets reads
+ *   `directories.assets`) and by the composition root (passthrough copy from
+ *   `directories.public`).
+ *
+ * Lifecycle:
+ *   build-time → synthesise key, pre-populate cache from eleventyConfig.dir
+ *   build-time → on `eleventy.directories`, refresh the cache to final paths
+ *
+ * Why this exists:
+ *   Eleventy's ProjectDirectories.setViaConfigObject() only honours input,
+ *   output, data, includes, and layouts. Extra `dir.*` keys are silently
+ *   ignored, and the `eleventy.directories` event exposes only the same set.
+ *   Synthesis fills the gap so consumers can read additional dirs the same
+ *   way they read the real ones.
+ *
+ * Scope:
+ *   Owns synthesis of extra `eleventyConfig.directories` keys, the live
+ *   cache, and a single shared listener for sync.
+ *   Does not own passthrough copy or watch wiring (composition root and
+ *   modules own those).
+ *
+ * Data flow:
+ *   { name, outputDir } → eleventyConfig.directories[name] getter →
+ *   live { input, output } cache → consumers
+ */
+
+const SCOPE_NAME = 'core:virtual-dir';
+
+/**
+ * Register a virtual directory on eleventyConfig.directories.
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @param {Object} options
+ * @param {string} options.key - Key to synthesise (e.g. 'assets', 'public').
+ * @param {string} [options.outputDir] - Override the output subdirectory. Defaults
+ *   to the raw dir value (symmetric with input). Pass `''` to resolve to the
+ *   output root (used by `public`, which copies to `/`).
+ * @returns {{input: string, output: string}} Live cache; properties refresh when
+ *   eleventy.directories fires. Safe to read at plugin-init time.
+ */
+export function registerVirtualDir(eleventyConfig, { key, outputDir } = {}) {
+	if (!key) {
+		throw new Error('registerVirtualDir: `name` is required');
+	}
+
+	const log = createLogger(SCOPE_NAME);
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+	const rawDir = eleventyConfig.dir?.[key] || key;
+	const rawOutputDir = outputDir ?? rawDir;
+	const cache = { input: null, output: null };
+
+	// Pre-populate from eleventyConfig.dir so synchronous readers at plugin-init
+	// time (watch globs, ignores, compile-guard prefixes) see a valid path.
+	syncCache(cache, eleventyConfig.dir || {}, rawDir, rawOutputDir);
+
+	setEntry(scope, key, { rawDir, rawOutputDir, cache });
+
+	// Define the virtual key once. The getter reads the live cache, which the
+	// shared listener below refreshes when Eleventy emits its final directories.
+	const existing = Object.getOwnPropertyDescriptor(eleventyConfig.directories, key);
+	if (existing && existing.configurable === false) {
+		log.info(`directories[${key}] already defined; skipping`);
+	} else {
+		Object.defineProperty(eleventyConfig.directories, key, {
+			get() {
+				return cache.input;
+			},
+			enumerable: true,
+			configurable: false
+		});
+	}
+
+	// One listener services all virtual dirs registered on this config.
+	// addScopeListener dedupes on ('eleventy.directories', 'sync'), so
+	// subsequent registerVirtualDir calls don't stack handlers.
+	addScopeListener(eleventyConfig, SCOPE_NAME, 'eleventy.directories', 'sync', (scope, dirs) => {
+		for (const entry of scope.values.values()) {
+			syncCache(entry.cache, dirs, entry.rawDir, entry.rawOutputDir);
+		}
+	});
+
+	log.info('Virtual directories mounted');
+
+	return cache;
+}
+
+function syncCache(cache, dirs, rawDir, rawOutputDir) {
+	const inputDir = TemplatePath.addLeadingDotSlash(dirs.input || './');
+	const outputDir = TemplatePath.addLeadingDotSlash(dirs.output || './');
+
+	// resolveSubdir symmetrically resolves against input and output; call twice
+	// so input and output subdirs can differ (e.g. `public` copies to root).
+	cache.input = resolveSubdir(inputDir, outputDir, rawDir).input;
+	cache.output = resolveSubdir(inputDir, outputDir, rawOutputDir).output;
+}

package/core/wikilinks.js

@@ -0,0 +1,152 @@
+import { slugify } from './utils/helpers.js';
+
+/**
+ * WIKILINKS (filter)
+ *
+ * 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);
+}