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

package/core/seo-graph/register.js

@@ -0,0 +1,42 @@
+import { createLogger } from '../logging/index.js';
+import { getScope, memoize } from '../registry.js';
+import { createSeoNamespace } from './build.js';
+
+const SCOPE_NAME = 'core:seo-graph';
+const LOG_NAME = 'seo-graph';
+const COMPUTED_KEY = 'eleventyComputed._seoGraph';
+
+/**
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} coreContext
+ */
+export function registerSeoGraph(eleventyConfig, coreContext) {
+	const { state, runtime } = coreContext;
+	const { settings, options } = state;
+
+	const log = createLogger(LOG_NAME, { verbose: options.verbose });
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	const buildSeoNamespace = createSeoNamespace({ scope, settings, runtime, options, log });
+
+	function shouldSkip(data) {
+		if (data._internal) return true;
+		if (data.page?.outputFileExtension !== 'html') return true;
+		return false;
+	}
+
+	eleventyConfig.addGlobalData(COMPUTED_KEY, () => {
+		return (data) => {
+			if (shouldSkip(data)) return data._seoGraph ?? null;
+			return memoize(scope, data, buildSeoNamespace);
+		};
+	});
+
+	log.info('SEO graph registered');
+
+	return {
+		get: (data) => scope.cache.get(data),
+		getByKey: (key) => scope.values.get(key),
+		snapshot: () => Object.fromEntries(scope.values)
+	};
+}

package/core/seo-graph/schema.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+// Structural shape of the resolved `seo` namespace. Permissive on values;
+// strict only where a missing/wrong shape would break a downstream consumer.
+export const seoSchema = z
+	.object({
+		title: z.string().optional(),
+		description: z.string().optional(),
+		url: z.string().optional(),
+		ogImage: z.unknown().optional(),
+		locale: z.string().optional(),
+		openGraph: z.record(z.unknown()).optional(),
+		twitter: z.record(z.unknown()).optional(),
+		// The assembled JSON-LD @graph. Authored identity lives at
+		// `data.schema`; the resolved graph lives here. No `seo.schema` path.
+		graph: z.array(z.unknown()).optional()
+	})
+	.passthrough();

package/core/state.js

@@ -39,8 +39,10 @@ export function deriveBaselineState(settings, options, { mode } = {}) {
 		url: settings.url,
 		noindex: settings.noindex ?? false,
 		defaultLanguage: settings.defaultLanguage,
+		defaultLocale: settings.defaultLocale,
 		languages: settings.languages,
-		head: settings.head
+		head: settings.head,
+		seo: settings.seo
 	};
 
 	const resolvedOptions = {

package/core/surface/index.js

@@ -5,7 +5,7 @@
  * user templates can reach: filters, global functions, shortcodes.
  */
 
-import { registerDateGlobal } from './global-date-function.js';
+import { registerDateGlobal } from '../dates/index.js';
 
 // --- Filters ---
 export { markdownFilter } from '../markdown/markdownify.js';

package/core/types.js

@@ -14,6 +14,9 @@
  * @property {string} [url]
  * @property {boolean} [noindex]
  * @property {string} [defaultLanguage]
+ * Short language code; a writer-side alias for defaultLocale.
+ * @property {string} [defaultLocale]
+ * BCP 47 default locale; preferred when both are set.
  * @property {Record<string, unknown>} [languages]
  * @property {Object} [head]
  */

package/core/utils/{normalize-languages.js → normalize-language-map.js}

@@ -1,13 +1,20 @@
 /**
- * Normalize language input to an object map.
- * Accepts an array of language codes or an object keyed by language code.
- * Returns undefined if input is invalid or empty.
+ * Normalize the `settings.languages` config into an object map with
+ * lowercased, trimmed keys.
+ *
+ * Accepts an array of language codes or an object keyed by language code;
+ * either form ends up with `[normalizedKey]: entry`. Returns undefined if
+ * the input is invalid or empty.
+ *
+ * Lives in `core/utils/` (not `core/locale/`) because the array-vs-object
+ * shape coercion is config-shape adapting, not locale handling. The
+ * lowercasing of keys is the only locale-shaped part.
  *
  * @param {Object} settings - Options object containing languages.
  * @param {import('../logging/index.js').BaselineLogger} [logger] - Logger for dropped-entry notice.
  * @returns {Record<string, Object>|undefined} Normalized language map, or undefined.
  */
-export function normalizeLanguages(settings, logger) {
+export function normalizeLanguageMap(settings, logger) {
 	const normalizedLanguages = Array.isArray(settings.languages)
 		? Object.fromEntries(
 				settings.languages
@@ -15,7 +22,9 @@ export function normalizeLanguages(settings, logger) {
 					.map((lang) => [lang.toLowerCase().trim(), {}])
 			)
 		: settings.languages && typeof settings.languages === 'object'
-			? settings.languages
+			? Object.fromEntries(
+					Object.entries(settings.languages).map(([k, v]) => [k.toLowerCase().trim(), v])
+				)
 			: undefined;
 
 	if (logger && Array.isArray(settings.languages)) {

package/core/utils/title-case-slug.js

@@ -0,0 +1,15 @@
+/**
+ * Title-case a URL slug for display: "core-reference" → "Core Reference".
+ * The rough inverse of {@link slugify}: splits on hyphens/underscores and
+ * capitalises each word.
+ *
+ * @param {string} slug
+ * @returns {string}
+ */
+export function titleCaseSlug(slug) {
+	return String(slug)
+		.split(/[-_]/)
+		.filter(Boolean)
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(' ');
+}

package/index.js

@@ -15,6 +15,7 @@ import { createContentMapStore } from './core/content-map-store.js';
 import { createTranslationMapStore } from './core/translation-map-store.js';
 import { createSlugIndex } from './core/slug-index.js';
 import { registerPageContext } from './core/page-context/index.js';
+import { registerSeoGraph } from './core/seo-graph/index.js';
 import { autoHeadingIds, safeUse, wikilinks } from './core/markdown/index.js';
 import { slugify } from './core/utils/slugify.js';
 import { assetsCore, headCore, multilangCore, navigatorCore, sitemapCore } from './modules.js';
@@ -50,9 +51,10 @@ const INTERNAL_KEYS = [
 	'_snapshot',
 	'eleventyComputed._pageContext',
 	'eleventyComputed._node',
-	'eleventyComputed._edges',
+	'eleventyComputed._seoGraph',
 	'eleventyComputed._backlinks',
-	'eleventyComputed._outgoing'
+	'eleventyComputed._outgoing',
+	'eleventyComputed._edges'
 ];
 
 // Base logger outputs regardless of options.
@@ -174,13 +176,14 @@ export default function baseline(settings = {}, options = {}) {
 		}
 
 		INTERNAL_KEYS.forEach((key) => {
-			// We leave eleventyComputed callback kEys alone, the rest are reserved-empty.
+			// We leave eleventyComputed callback keys alone, the rest are reserved-empty.
 			if (
 				key === 'eleventyComputed._pageContext' ||
 				key === 'eleventyComputed._node' ||
-				key === 'eleventyComputed._edges' ||
+				key === 'eleventyComputed._seoGraph' ||
 				key === 'eleventyComputed._backlinks' ||
-				key === 'eleventyComputed._outgoing'
+				key === 'eleventyComputed._outgoing' ||
+				key === 'eleventyComputed._edges'
 			)
 				return;
 			eleventyConfig.addGlobalData(key, {});
@@ -286,8 +289,9 @@ export default function baseline(settings = {}, options = {}) {
 			helpers
 		};
 
-		// Page context registry
+		// Page context and SEO graph registries
 		const pageContextRegistry = registerPageContext(eleventyConfig, coreContext);
+		const seoGraphRegistry = registerSeoGraph(eleventyConfig, coreContext);
 
 		// --- Content graph ---
 		// Cascade hookup for the content graph. Reads via the runtime getter so
@@ -338,7 +342,8 @@ export default function baseline(settings = {}, options = {}) {
 		// --- Snapshots ---
 		coreContext.snapshots = {
 			contentMap: () => contentMapStore.snapshot(),
-			pageContext: () => pageContextRegistry.snapshot()
+			pageContext: () => pageContextRegistry.snapshot(),
+			seoGraph: () => seoGraphRegistry.snapshot()
 		};
 
 		// --- Module registry ---
@@ -346,7 +351,7 @@ export default function baseline(settings = {}, options = {}) {
 			{ when: state.features.multilang, name: 'multilang', plugin: multilangCore },
 			{ when: state.features.sitemap, name: 'sitemap', plugin: sitemapCore },
 			{ name: 'navigator', plugin: navigatorCore },
-			{ when: state.features.head, name: 'head', plugin: headCore, consumes: { pageContext: true } },
+			{ when: state.features.head, name: 'head', plugin: headCore, consumes: { pageContext: true, seoGraph: true } },
 			{ when: state.features.assets, name: 'assets', plugin: assetsCore }
 		];
 
@@ -357,7 +362,8 @@ export default function baseline(settings = {}, options = {}) {
 			const moduleContext = {
 				...coreContext,
 				log: scopedLog(name),
-				resolvePageContext: consumes.pageContext ? pageContextRegistry : null
+				resolvePageContext: consumes.pageContext ? pageContextRegistry : null,
+				resolveSeoGraph: consumes.seoGraph ? seoGraphRegistry : null
 			};
 
 			eleventyConfig.addPlugin(plugin, moduleContext);

package/modules/head/drivers/posthtml-head-elements.js

@@ -27,28 +27,41 @@ import { dedupeMeta, dedupeLink } from '../utils/dedupe.js';
  *
  * Scope:
  *   Owns node emission, dedupe orchestration, capo sort, and placeholder
- *   replacement.
- *   Does not own seed shape (page context), hreflang building
- *   (head/utils/alternates.js), or capo's element weights (capo.js).
+ *   replacement. Owns the og:/twitter: vocabulary: the seo substrate hands
+ *   over short structured keys, this driver maps them to <meta>/<script>.
+ *   Does not own seed shape (page context), the seo projection
+ *   (core/seo-graph), hreflang building (head/utils/alternates.js), or capo's
+ *   element weights (capo.js).
  *
  * Data flow:
- *   seeds + alternates + options → emit → dedupe → capo-sort → PostHTML
+ *   seeds + seo + alternates + options → emit → dedupe → capo-sort → PostHTML
  *   tree mutation
  *
  * @param {Object} args
  * @param {Object} args.seeds - Page context for the current page.
+ * @param {Object} [args.seo] - Resolved _seoGraph namespace (url, schema, openGraph, twitter).
  * @param {Array<Object>} args.alternates - hreflang link descriptors.
  * @param {Object} args.options - Head options (titleSeparator, showGenerator).
  * @param {string} args.placeholderTag - Placeholder element to replace.
  * @param {string} args.eol - End-of-line separator interleaved between nodes.
  * @returns {(tree: Object) => Object} PostHTML plugin function.
  */
-export function renderHead({ seeds, alternates, options, placeholderTag, eol }) {
-	const defaults = emitMeta(seeds.meta, seeds.render, options);
+export function renderHead({ seeds, seo, alternates, options, placeholderTag, eol }) {
+	// seo.url is the canonical source, resolved at cascade-time. It is undefined
+	// on noindex / no-settings.url pages, where the seo layer deliberately drops
+	// the canonical — emitMeta's guard then emits nothing, which is correct. The
+	// seo handle is present whenever a head renders (same skip set as page
+	// context), so there is no absent-handle case to fall back for.
+	const canonical = seo?.url;
+	const defaults = emitMeta(seeds.meta, seeds.render, options, canonical);
 	const extras = emitExtras(seeds.head, alternates);
+	const { meta: seoMeta, multi: seoMulti, scripts: seoScripts } = emitSeo(seo);
 
-	const deduped = dedupeAll([...defaults, ...extras]);
-	const sorted = capoSort(deduped);
+	// seo emits last so the substrate wins a property collision with settings.head.
+	// Multi-valued tags and JSON-LD bypass dedupe (property-keyed last-wins would
+	// collapse repeated og:locale:alternate / article:author to one).
+	const deduped = dedupeAll([...defaults, ...extras, ...seoMeta]);
+	const sorted = capoSort([...deduped, ...seoMulti, ...seoScripts]);
 
 	return function rendererPlugin(tree) {
 		tree.match({ tag: placeholderTag }, () => ({
@@ -59,14 +72,14 @@ export function renderHead({ seeds, alternates, options, placeholderTag, eol })
 	};
 }
 
-function emitMeta(meta, render, options) {
+function emitMeta(meta, render, options, canonical) {
 	const nodes = [];
 	nodes.push(mkMeta({ charset: 'UTF-8' }));
 	nodes.push(mkMeta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }));
 	if (meta.title) nodes.push({ tag: 'title', content: [meta.title] });
 	if (meta.description) nodes.push(mkMeta({ name: 'description', content: meta.description }));
 	nodes.push(mkMeta({ name: 'robots', content: meta.robots }));
-	if (meta.canonical) nodes.push(mkLink({ rel: 'canonical', href: meta.canonical }));
+	if (canonical) nodes.push(mkLink({ rel: 'canonical', href: canonical }));
 	if (options.showGenerator && render.generator) {
 		nodes.push(mkMeta({ name: 'generator', content: render.generator }));
 	}
@@ -74,6 +87,75 @@ function emitMeta(meta, render, options) {
 	return nodes;
 }
 
+/**
+ * Map the resolved seo projection to head nodes. The substrate hands over short
+ * structured keys; this driver owns the og:/twitter: vocabulary. Single-valued
+ * tags ride the deduped meta flow; multi-valued ones (og:locale:alternate,
+ * repeated article:author / article:tag) go in `multi` to skip the property-keyed dedupe.
+ * The JSON-LD graph rides `scripts` (the adapter returns a bare @graph array,
+ * wrapped in its @context envelope here).
+ *
+ * @param {Object} [seo] - Resolved seo namespace (graph, openGraph, twitter).
+ * @returns {{ meta: Array<Object>, multi: Array<Object>, scripts: Array<Object> }}
+ */
+function emitSeo(seo) {
+	const meta = [];
+	const multi = [];
+	const scripts = [];
+	if (!seo) return { meta, multi, scripts };
+
+	const og = seo.openGraph ?? {};
+	const tw = seo.twitter ?? {};
+
+	const prop = (property, content) => {
+		if (content !== undefined && content !== null && content !== '') meta.push(mkMeta({ property, content }));
+	};
+	const name = (key, content) => {
+		if (content !== undefined && content !== null && content !== '') meta.push(mkMeta({ name: key, content }));
+	};
+
+	prop('og:title', og.title);
+	prop('og:type', og.type);
+	prop('og:description', og.description);
+	prop('og:url', og.url);
+	prop('og:site_name', og.siteName);
+	prop('og:locale', og.locale);
+	prop('og:image', og.image);
+	prop('og:image:alt', og.imageAlt);
+	if (og.imageWidth !== undefined) prop('og:image:width', String(og.imageWidth));
+	if (og.imageHeight !== undefined) prop('og:image:height', String(og.imageHeight));
+
+	for (const loc of asArray(og.localeAlternate)) {
+		if (loc) multi.push(mkMeta({ property: 'og:locale:alternate', content: loc }));
+	}
+
+	if (og.article) {
+		prop('article:published_time', og.article.publishedTime);
+		prop('article:modified_time', og.article.modifiedTime);
+		prop('article:section', og.article.section);
+		for (const author of asArray(og.article.authors)) {
+			if (author) multi.push(mkMeta({ property: 'article:author', content: author }));
+		}
+		for (const tag of asArray(og.article.tags)) {
+			if (tag) multi.push(mkMeta({ property: 'article:tag', content: tag }));
+		}
+	}
+
+	name('twitter:card', tw.card);
+	name('twitter:site', tw.site);
+	name('twitter:creator', tw.creator);
+	name('twitter:title', tw.title);
+	name('twitter:description', tw.description);
+	name('twitter:image', tw.image);
+
+	if (seo.schema?.length) {
+		const content = JSON.stringify({ '@context': 'https://schema.org', '@graph': seo.schema });
+		scripts.push(mkScript({ type: 'application/ld+json', content }));
+	}
+
+	return { meta, multi, scripts };
+}
+
 function emitExtras(head, alternates = []) {
 	const nodes = [];
 	for (const m of asArray(head?.meta)) nodes.push(mkMeta(m));

package/modules/head/index.js

@@ -33,15 +33,16 @@ const EOL = '\n';
  *   every field the composer needs from cascade-time into transform-time.
  *
  * Scope:
- *   Owns transform-time composition and placeholder replacement.
- *   Pass 1 covers bucket 1 only: charset, viewport, title, description,
- *   robots, canonical, optional generator, plus user extras from
- *   settings.head and hreflang alternates. SEO and JSON-LD are later passes.
- *   Does not own seed shape (page context) or driver internals.
+ *   Owns transform-time composition and placeholder replacement. Emits
+ *   charset, viewport, title, description, robots, canonical, optional
+ *   generator, user extras from settings.head, hreflang alternates, plus the
+ *   seo substrate's OG/Twitter projections and JSON-LD graph.
+ *   Does not own seed shape (page context), the seo projection
+ *   (core/seo-graph), or driver internals.
  *
  * Data flow:
- *   page context + translation-map store + settings.head → driver →
- *   PostHTML tree mutation (replaces <baseline-head>)
+ *   page context + seo handle + translation-map store + settings.head →
+ *   driver → PostHTML tree mutation (replaces <baseline-head>)
  *
  * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
  * @param {Object} moduleContext
@@ -59,6 +60,7 @@ export function headCore(eleventyConfig, moduleContext) {
 	}
 
 	const pageContextRegistry = moduleContext.resolvePageContext;
+	const seoGraphRegistry = moduleContext.resolveSeoGraph;
 
 	// Resolved plugin options with defaults.
 	const headOptions = {
@@ -86,14 +88,19 @@ export function headCore(eleventyConfig, moduleContext) {
 			return (tree) => tree;
 		}
 
-		const translationKey = seeds.page?.locale?.translationKey;
+		// Peer substrate, read by the same key as the page context above. Carries
+		// the resolved canonical, OG/Twitter projections, and the JSON-LD graph.
+		const seo = seoGraphRegistry?.getByKey(key);
+
+		const translationKey = seeds.page?.translationKey;
 
 		const alternates = translationKey
-			? buildAlternates(seeds.page?.locale?.translationKey, runtime.translationMap.get(), seeds.site?.url)
+			? buildAlternates(translationKey, runtime.translationMap.get(), seeds.site?.url)
 			: [];
 
 		return renderHead({
 			seeds,
+			seo,
 			alternates,
 			options: headOptions,
 			placeholderTag: PLACEHOLDER_TAG,

package/modules/head/schema.js

@@ -6,6 +6,7 @@ import * as z from 'zod';
 // `options.head` slice: render-behaviour knobs.
 export const optionsSchema = z.looseObject({
 	titleSeparator: z.string().optional(),
+	titleTemplate: z.string().optional(),
 	showGenerator: z.boolean().optional()
 });
 
@@ -17,10 +18,13 @@ export const settingsHeadSchema = z.looseObject({
 	style: z.array(z.looseObject({})).optional()
 });
 
-// `settings.seo` site-default SEO scalars, page-overridable.
+// `settings.seo` site-default SEO config: canonical policy, default share
+// image, and OG/Twitter defaults. Structural only; values stay permissive.
 export const settingsSeoSchema = z.looseObject({
-	ogImage: z.string().optional(),
-	twitterSite: z.string().optional()
+	preserveQueryParams: z.boolean().optional(),
+	ogImage: z.unknown().optional(),
+	openGraph: z.looseObject({}).optional(),
+	twitter: z.looseObject({}).optional()
 });
 
 // Page-level `seo:` block. Same scalar set as bare front matter, namespaced.

package/modules/multilang/filters/i18n-default-translation.js

@@ -5,10 +5,8 @@
  * @returns {object|null}
  */
 export default function i18nDefaultTranslation(page, collection) {
-	if (!page?.locale?.translationKey) return null;
+	if (!page?.translationKey) return null;
 	return (
-		collection.find(
-			(p) => p.locale && p.locale.translationKey === page.locale.translationKey && p.locale.isDefaultLang
-		) || null
+		collection.find((p) => p.translationKey === page.translationKey && p.isDefaultLang) || null
 	);
 }

package/modules/multilang/filters/i18n-translation-in.js

@@ -6,11 +6,11 @@
  * @returns {object|null}
  */
 export default function i18nTranslationIn(page, collection, lang) {
-	if (!page?.locale?.translationKey) return null;
+	if (!page?.translationKey) return null;
 
 	return (
 		collection.find(
-			(p) => p.locale && p.locale.translationKey === page.locale.translationKey && p.locale.lang === lang
+			(p) => p.translationKey === page.translationKey && p.lang === lang
 		) || null
 	);
 }

package/modules/multilang/filters/i18n-translations-for.js

@@ -5,6 +5,6 @@
  * @returns {Array<object>}
  */
 export default function i18nTranslationsFor(page, collection) {
-	if (!page?.locale?.translationKey) return [];
-	return collection.filter((p) => p.locale && p.locale.translationKey === page.locale.translationKey);
+	if (!page?.translationKey) return [];
+	return collection.filter((p) => p.translationKey === page.translationKey);
 }