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

package/modules/navigator/index.js

@@ -10,39 +10,42 @@ const __dirname = path.dirname(__filename);
 /**
  * Navigator (module)
  *
- * Debug surface. Exposes Eleventy and Baseline runtime state to templates so
- * developers can inspect data shape, scope contents, and lifecycle output
- * without leaving the page.
+ * Two roles, one module: the public read surface for plugin-produced
+ * cross-page data (the content graph and its enriched backlinks), and the
+ * debug surface for inspecting Eleventy and Baseline runtime state.
  *
  * Architecture layer:
  *   module
  *
  * System role:
- *   Read-only window into the runtime substrate. Pulls snapshots from the
- *   page-context registry and content-map store via the module context;
- *   does not write back.
+ *   Read-only window over the runtime substrate. Surfaces the content graph
+ *   for templates that need cross-page reads, and snapshots from the
+ *   page-context registry and content-map store for debugging. Writes
+ *   nothing back.
  *
  * Lifecycle:
- *   build-time   → register Nunjucks globals, debug filters, and the
- *                  optional virtual debug page
+ *   build-time   → register `_navigator` ({ nodes, edges, backlinks }),
+ *                  debug globals, filters, and the optional virtual debug page
  *   cascade-time → eleventyComputed `_snapshot` resolves contentMap and
  *                  pageContext on each page
  *
  * Why this exists:
- *   Render-time inspection of cascade state has no built-in surface.
- *   Centralising globals and filters under a debug-only module keeps the
- *   inspection vocabulary stable and out of feature modules.
+ *   Templates need an addressable cross-page surface for graph reads, and
+ *   render-time inspection of cascade state has no built-in equivalent.
+ *   One module owns both vocabularies so feature modules stay narrow.
  *
  * Scope:
- *   Owns the `_runtime` and `_ctx` Nunjucks globals, computed `_snapshot`,
+ *   Owns the `_navigator` global (`{ nodes, edges, backlinks }`, the public
+ *   read surface), the debug globals `_runtime` and `_ctx`, computed `_snapshot`,
  *   debug filters (`_inspect`, `_json`, `_keys`), and the optional virtual
  *   page at /navigator-core.html.
- *   Does not own the data it surfaces (page-context registry, content-map
- *   store).
+ *   Does not own the data it surfaces (content graph, page-context registry,
+ *   content-map store).
  *
  * Data flow:
- *   snapshots (contentMap, pageContext) + this.ctx → globals + computed
- *   `_snapshot` + virtual page → developer
+ *   runtime.contentGraph + snapshots + this.ctx → `_navigator` + debug
+ *   globals + computed `_snapshot` + virtual page → templates and
+ *   developers
  *
  * Note: `_snapshot.contentMap` is null on the navigator template itself
  * because it renders before `eleventy.contentMap` fires. Read `_snapshot`
@@ -51,23 +54,25 @@ const __dirname = path.dirname(__filename);
  * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
  * @param {Object} moduleContext
  * @param {Object} moduleContext.state - Resolved plugin state.
+ * @param {Object} moduleContext.runtime - Lazy access layer; reads contentGraph.
  * @param {Object} moduleContext.snapshots - Thunks: { contentMap, pageContext }.
  */
 export function navigatorCore(eleventyConfig, moduleContext) {
-	const { state, snapshots, log, env } = moduleContext;
+	const { state, runtime, snapshots, log, env } = moduleContext;
 	const { settings, options } = state;
 
 	// Structural-only options check: log on mismatch, do not throw.
 	const parsed = optionsSchema.safeParse(options.navigator);
 	if (!parsed.success) {
 		for (const issue of parsed.error.issues) {
-			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+			log.info('options:', `${issue.path.join('.')}, ${issue.message}`);
 		}
 	}
 
 	// Boolean shorthand activates the virtual page; object form lets users tune.
 	const navigatorOpts = options.navigator && typeof options.navigator === 'object' ? options.navigator : {};
-	const renderTemplate = env.mode === 'development' ?? navigatorOpts.template ?? Boolean(options.navigator);
+	const renderTemplate =
+		navigatorOpts.template ?? (typeof options.navigator === 'boolean' ? options.navigator : env.mode === 'development');
 	const inspectorDepth = navigatorOpts.inspectorDepth ?? 4;
 
 	eleventyConfig.addGlobalData('eleventyComputed._snapshot', () => {
@@ -77,6 +82,14 @@ export function navigatorCore(eleventyConfig, moduleContext) {
 		});
 	});
 
+	// Public read surface for plugin-produced cross-page data. Templates can
+	// paginate over `_navigator.backlinks` or read `_navigator.graph` directly.
+	eleventyConfig.addGlobalData('_navigator', () => ({
+		nodes: runtime.contentGraph?.nodes ?? {},
+		edges: runtime.contentGraph?.edges ?? {},
+		backlinks: runtime.contentGraph?.backlinks ?? {}
+	}));
+
 	/**
 	 * Nunjucks Global: _runtime
 	 *
@@ -125,7 +138,7 @@ export function navigatorCore(eleventyConfig, moduleContext) {
 			inspectorDepth
 		});
 
-		log.info('Navigator template registered at /navigator-core.html');
+		log.info('Navigator mounted at /navigator-core.html');
 	}
 
 	/**

package/modules/navigator/templates/navigator-core.html

@@ -41,7 +41,7 @@ permalink: /navigator-core.html
 			<details>
 				<summary><strong>Page Context</strong></summary>
 				<pre>
-					{{- _snapshot.pageContext | _inspect({ depth: null }) -}}
+					{{- _pageContext | _inspect({ depth: null }) -}}
 				</pre>
 			</details>
 			{% for key, value in _runtime() %}

package/modules/sitemap/index.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { normalizeLanguages } from '../../core/utils/helpers.js';
+import { normalizeLanguages } from '../../core/utils/normalize-languages.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -19,7 +19,7 @@ const __dirname = path.dirname(__filename);
  *
  * System role:
  *   Reads the same normalised language map as multilang (via
- *   core/utils/helpers.js) and emits virtual templates that Eleventy
+ *   core/utils/normalize-languages.js) and emits virtual templates that Eleventy
  *   renders to XML. Pages opt out via `noindex` in the cascade.
  *
  * Lifecycle:
@@ -37,7 +37,7 @@ const __dirname = path.dirname(__filename);
  *   Owns computed page.sitemap and the virtual sitemap templates
  *   (single-language /sitemap.xml, or per-lang /{lang}/sitemap.xml plus a
  *   /sitemap.xml index).
- *   Does not own language normalisation (core/utils/helpers.js) or noindex
+ *   Does not own language normalisation (core/utils/normalize-languages.js) or noindex
  *   propagation through the cascade.
  *
  * Data flow:
@@ -108,6 +108,8 @@ export function sitemapCore(eleventyConfig, moduleContext) {
 			languages: languages,
 			_internal: true
 		});
+
+		log.info('Sitemaps written per-language');
 	} else {
 		eleventyConfig.addTemplate('_baseline/sitemap-core.html', baseContent, {
 			permalink: '/sitemap.xml',
@@ -117,5 +119,7 @@ export function sitemapCore(eleventyConfig, moduleContext) {
 			eleventyExcludeFromCollections: true,
 			_internal: true
 		});
+
+		log.info('Sitemap written');
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apleasantview/eleventy-plugin-baseline",
-  "version": "0.1.0-next.39",
+  "version": "0.1.0-next.41",
   "description": "An experimental Swiss army knife toolkit for Eleventy",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
   "bugs": {
     "url": "https://github.com/apleasantview/eleventy-plugin-baseline/issues"
   },
-  "homepage": "https://eleventy-plugin-baseline.netlify.app/",
+  "homepage": "https://www.eleventy-baseline.dev/",
   "peerDependencies": {
     "@11ty/eleventy": ">=3.1.0",
     "@11ty/eleventy-img": "^6.0.4"
@@ -46,8 +46,10 @@
     "dotenv": "^17.2.3",
     "esbuild": "0.27.0",
     "kleur": "^4.1.5",
+    "linkedom": "^0.18.12",
     "luxon": "^3.7.2",
     "markdown-it": "^14.1.1",
+    "markdown-it-attrs": "^4.3.1",
     "postcss": "^8.5.6",
     "postcss-import": "^16.1.1",
     "postcss-import-ext-glob": "^2.1.1",

package/core/filters/index.js

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

package/core/global-functions/index.js

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

package/core/logging.js

@@ -1,32 +0,0 @@
-import chalk from 'kleur';
-
-/**
- * @typedef {Object} BaselineLogger
- * @property {(...args: unknown[]) => void} info   Verbose-only.
- * @property {(...args: unknown[]) => void} warn   Always visible.
- * @property {(...args: unknown[]) => void} error  Always visible.
- */
-
-/**
- * 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 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

@@ -1,310 +0,0 @@
-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/shortcodes/index.js

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

package/core/utils/helpers.js

@@ -1,75 +0,0 @@
-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;
-}