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

package/README.md

@@ -2,9 +2,9 @@
 
 Baseline makes the structural decisions that Eleventy leaves open: directory layout, asset pipeline, image handling, SEO, sitemaps.
 
-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.
+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.
 
-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.
+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.
 
 This is a working plugin, not a finished product. Things might shift, break, or get renamed.
 
@@ -33,14 +33,14 @@ export const config = baselineConfig;
 
 `baseline()` returns an async closure (Eleventy's documented async-plugin pattern), so the call to `addPlugin` is awaited.
 
-The plugin takes two arguments: `settings` (site identity — title, url, languages, head extras) and `options` (runtime behavior — verbose, sitemap, navigator).
+The plugin takes two arguments: `settings` (site identity – title, url, languages, head extras, SEO defaults) and `options` (runtime behavior – verbose, sitemap, navigator).
 
 ```js
 const settings = {
 	title: 'My Site',
 	tagline: 'Built with Baseline',
 	url: 'https://www.example.com/',
-	defaultLanguage: 'en',
+	defaultLocale: 'en-US',
 	languages: {
 		en: { title: 'My Site' },
 		nl: { title: 'Mijn Site' }
@@ -60,30 +60,30 @@ await eleventyConfig.addPlugin(
 
 The plugin registers everything on load. No setup beyond the config above.
 
-**Core** — always active:
+**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.
-- Wikilinks in Markdown — `[[slug]]`, `[[slug:lang]]`, `[[slug#anchor]]`, `[[slug|alias]]`, combinable. Forward links only.
-- Auto heading IDs — every heading gets a stable slugified `id` with WordPress-style dedup; manual `{#id}` always wins.
-- Element attributes in Markdown — `{#id .class key="value"}` syntax attaches attributes to any block element (via `markdown-it-attrs`).
+- An image shortcode (via eleventy-img) – AVIF and WebP, responsive widths, lazy loading. Alt text is required – the build warns if you skip it.
+- Wikilinks in Markdown – `[[slug]]`, `[[slug:lang]]`, `[[slug#anchor]]`, `[[slug|alias]]`, combinable. Forward links only.
+- Auto heading IDs – every heading gets a stable slugified `id` with WordPress-style dedup; manual `{#id}` always wins.
+- Element attributes in Markdown – `{#id .class key="value"}` syntax attaches attributes to any block element (via `markdown-it-attrs`).
 - Filters: `markdownify`, `relatedPosts`, `isString`
 - A date-formatting global
-- Drafts preprocessor — drafts stay out of production builds automatically
+- Drafts preprocessor – drafts stay out of production builds automatically
 - Static passthrough (`src/static/` → site root)
 
-**Modules** — `head` and `assets` are always on; `sitemap` is on by default; `navigator` is on in development; `multilang` is opt-in.
+**Modules** – `head` and `assets` are always on; `sitemap` is on by default; `navigator` is on in development; `multilang` is opt-in.
 
-| 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                                                                                         |
+| 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 handled for you by dropping `<baseline-head>` in your layout: charset, viewport, title, description, robots, canonical, hreflang, plus a full SEO payload (Open Graph, Twitter Cards, and a JSON-LD structured-data graph) |
+| `multilang` | Directory-based multilingual support. Per-language collections, translation mapping, i18n filters. Wraps Eleventy's I18n plugin                                                                                                          |
+| `navigator` | The content-graph read surface (`_navigator`: nodes, edges, backlinks), plus debug tooling: globals for inspecting template data, debug filters (`_inspect`, `_json`, `_keys`), and an 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
 
-Full documentation — tutorials, how-to guides, and reference — lives at:
+Full documentation – tutorials, how-to guides, and reference – lives at:
 [https://www.eleventy-baseline.dev/](https://www.eleventy-baseline.dev/)
 
 ## Contributing

package/core/content-graph/extractors.js

@@ -31,20 +31,58 @@ import { slugify } from '../utils/slugify.js';
  *   parsed document + knownOrigins → per-page record
  */
 
+// Live DOM id wins (matches anchored markup); fall back to a slugified id
+// so consumers always have a stable handle, even when the rendering pipeline
+// did not auto-anchor headings.
+function headingRecord(el) {
+	const text = (el.textContent || '').trim();
+	return {
+		level: Number(el.tagName[1]),
+		text,
+		id: el.id || slugify(text) || null
+	};
+}
+
 function extractHeadings(root) {
 	const nodes = root.querySelectorAll('h1, h2, h3, h4, h5, h6');
+	return Array.from(nodes).map(headingRecord);
+}
 
-	return Array.from(nodes).map((el) => {
-		const text = (el.textContent || '').trim();
-		// Live DOM id wins (matches anchored markup); fall back to a slugified
-		// id so consumers always have a stable handle, even when the rendering
-		// pipeline did not auto-anchor headings.
-		return {
-			level: Number(el.tagName[1]),
-			text,
-			id: el.id || slugify(text) || null
-		};
-	});
+function extractSections(root) {
+	const rootLevel = 2;
+	const sections = [];
+	let current = null;
+
+	// Shallow walk: markdown-rendered HTML keeps headings as siblings of
+	// their prose, which is the shape sections need.
+	for (const el of Array.from(root.children)) {
+		const isHeading = /^H[1-6]$/.test(el.tagName);
+		const level = isHeading ? Number(el.tagName[1]) : null;
+
+		if (isHeading && level === rootLevel) {
+			if (current) sections.push(finalizeSection(current));
+			current = { heading: headingRecord(el), parts: [] };
+			continue;
+		}
+
+		// H1 is the document title. Never opens a section, never folds in.
+		if (isHeading && level < rootLevel) continue;
+
+		// Pre-H2 content has no section to attach to; `excerpt` covers the lead.
+		if (current) current.parts.push(el);
+	}
+
+	if (current) sections.push(finalizeSection(current));
+	return sections;
+}
+
+function finalizeSection({ heading, parts }) {
+	const text = parts
+		.map((el) => el.textContent || '')
+		.join(' ')
+		.replace(/\s+/g, ' ')
+		.trim();
+	return { heading, text };
 }
 
 function extractLinks(root, currentPage, knownOrigins) {
@@ -52,21 +90,27 @@ function extractLinks(root, currentPage, knownOrigins) {
 
 	return Array.from(anchors).map((a) => {
 		const raw = a.getAttribute('href');
-		const page = currentPage;
 		const href = normaliseHref(raw, knownOrigins);
-		const internal = isInternal(href);
-		const type = internal ? 'link' : 'external';
 
 		return {
-			internal,
-			from: page,
+			internal: isInternal(href),
+			from: currentPage,
 			to: href,
-			type: type,
-			text: (a.textContent || '').trim()
+			text: (a.textContent || '').trim(),
+			rel: extractRel(a)
 		};
 	});
 }
 
+// HTML `rel` is a space-separated token list, case-insensitive per spec.
+// Lowercased and deduped so consumers can do membership checks without
+// caring about author-side whitespace or casing.
+function extractRel(el) {
+	const raw = el.getAttribute('rel');
+	if (!raw) return [];
+	return Array.from(new Set(raw.trim().toLowerCase().split(/\s+/).filter(Boolean)));
+}
+
 // HtmlBasePlugin rewrites internal hrefs to absolute URLs at render time
 // (using process.env.URL or the dev server origin). Strip a known origin
 // so hrefs land back as path-only; leave external URLs alone.
@@ -133,6 +177,7 @@ export function extractGraph(document, options = {}) {
 		node: {
 			excerpt: extractExcerpt(root, text),
 			headings: extractHeadings(root),
+			sections: extractSections(root),
 			images: extractImages(root)
 		},
 		edges: extractLinks(root, currentpage, knownOrigins)

package/core/content-graph/graph.js

@@ -41,7 +41,7 @@ import { buildBacklinkIndex } from './backlinks.js';
 /**
  * @param {Array<{ url: string, content?: string, data?: object }>} pages
  * @param {{ knownOrigins?: Set<string>, log?: { warn: (...args: unknown[]) => void } }} [options] - Origins to strip from internal hrefs (HtmlBasePlugin rewrites them at render time). `log` routes dev-mode extraction warnings through the scoped logger.
- * @returns {{ nodes: Record<string, object>, edges: Array<{ internal: boolean, from: string, to: string, type: string, text: string }>, backlinks: Record<string, Array<{ url: string, title?: string, excerpt?: string }>> }}
+ * @returns {{ nodes: Record<string, object>, edges: Array<{ internal: boolean, from: string, to: string, text: string, rel: string[] }>, backlinks: Record<string, Array<{ url: string, title?: string, excerpt?: string }>> }}
  */
 export function buildGraph(pages, options = {}) {
 	const { log } = options;
@@ -53,7 +53,7 @@ export function buildGraph(pages, options = {}) {
 		if (!page?.url || typeof page.content !== 'string') continue;
 		if (!page.outputPath?.endsWith('.html')) continue;
 		// Honour the same opt-out 404s, drafts and internal templates already use.
-		if (page.data?.eleventyExcludeFromCollections === true) continue;
+		if (page.data?._internal === true) continue;
 		if (page.data?.baselineExcludeFromGraph === true) continue;
 
 		try {
@@ -68,9 +68,12 @@ export function buildGraph(pages, options = {}) {
 				slug: ctx.entry?.slug,
 				description: ctx.entry?.description,
 				section: ctx.entry?.section,
+				breadcrumbs: ctx.entry?.breadcrumbs,
 				type: ctx.entry?.type,
 				lang: ctx.page?.lang,
 				locale: ctx.page?.locale,
+				translationKey: ctx.page?.translationKey,
+				isDefaultLang: ctx.page?.isDefaultLang,
 				date: ctx.page?.date,
 				url
 			};

package/core/dates/git-date.js

@@ -0,0 +1,71 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+let cache = null;
+
+// Build a { repoRelativePath: ISO date } map from one `git log` walk.
+// Each commit emits its date, then the files it touched; first date wins
+// because git log is newest-first.
+function buildCache() {
+	const map = new Map();
+	const marker = '__BASELINE_COMMIT__';
+	let raw;
+	try {
+		raw = execFileSync(
+			'git',
+			['log', '--name-only', '--no-renames', `--pretty=format:${marker}%cI`],
+			{ encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }
+		);
+	} catch {
+		return map;
+	}
+
+	let currentDate = null;
+	for (const line of raw.split('\n')) {
+		if (line.startsWith(marker)) {
+			// Normalise to UTC so all outputs (sitemap, JSON-LD, schemamap) match.
+			currentDate = new Date(line.slice(marker.length)).toISOString();
+		} else if (line && currentDate && !map.has(line)) {
+			map.set(line, currentDate);
+		}
+	}
+	return map;
+}
+
+function normalize(inputPath) {
+	const abs = path.resolve(inputPath);
+	const rel = path.relative(process.cwd(), abs);
+	return rel.split(path.sep).join('/');
+}
+
+/**
+ * Last-commit date (UTC ISO) for a file, or `null` when git has no record of
+ * it (untracked, or no git history available — e.g. a shallow CI clone).
+ *
+ * Unlike the docs-site copy this carries no mtime/now fallback: the date floor
+ * is `page.date`, applied by `resolveDates`, so this stays a pure "what does
+ * git say, or nothing" lookup.
+ *
+ * @param {string} inputPath
+ * @returns {string | null}
+ */
+export function gitModified(inputPath) {
+	if (!cache) cache = buildCache();
+	return cache.get(normalize(inputPath)) ?? null;
+}
+
+/**
+ * The most recent `gitModified` across several paths, or `null` if none resolve.
+ *
+ * @param {Array<string | undefined | null>} inputPaths
+ * @returns {string | null}
+ */
+export function maxGitModified(inputPaths) {
+	let max = null;
+	for (const p of inputPaths) {
+		if (!p) continue;
+		const iso = gitModified(p);
+		if (iso && (!max || iso > max)) max = iso;
+	}
+	return max;
+}

package/core/dates/index.js

@@ -0,0 +1,55 @@
+/**
+ * Dates substrate
+ *
+ * One home for date concerns: the Nunjucks `date` global (formatting), the
+ * git-backed last-commit lookup, and `resolveDates` — the single source for a
+ * page's publish/modified dates that the seo-graph substrate and any other
+ * consumer read from instead of re-deriving the chain.
+ */
+
+import { gitModified, maxGitModified } from './git-date.js';
+
+export { registerDateGlobal } from './date-global.js';
+export { gitModified, maxGitModified };
+
+/** Coerce a value to a valid `Date`, or `undefined` if it can't be parsed. */
+function toDate(value) {
+	if (!value) return undefined;
+	const d = value instanceof Date ? value : new Date(value);
+	return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+/**
+ * Resolve a page's publish and modified dates from one place. All three author
+ * keys are optional; the chain degrades to `page.date`, which Eleventy always
+ * backfills (front matter, else file birthtime), so output is never empty.
+ *
+ * - `datePublished` → front-matter `datePublished` → `page.date` (the floor).
+ * - `dateModified` → front-matter `dateModified` → git last-commit → resolved
+ *   `datePublished`.
+ *
+ * `git-date` is the middle rung of the modified chain and is allowed to yield
+ * nothing; flooring `dateModified` to the *resolved* `datePublished` (not raw
+ * `page.date`) keeps the pair coherent when an author overrides `datePublished`.
+ * No clamp to `modified >= published`: a scheduled post can legitimately be
+ * modified before its publish date.
+ *
+ * Takes the full cascade `data` bag (matches the substrate convention) and
+ * returns normalised `Date` objects, ready for the seo-graph piece builders.
+ *
+ * `gitLookup` is an injection seam for tests; production calls pass `data` only
+ * and get the real git-backed lookup.
+ *
+ * @param {{ page?: any, datePublished?: unknown, dateModified?: unknown }} data
+ * @param {(inputPath: string) => string | null} [gitLookup]
+ * @returns {{ datePublished: Date | undefined, dateModified: Date | undefined }}
+ */
+export function resolveDates(data, gitLookup = gitModified) {
+	const page = data?.page ?? {};
+	const datePublished = toDate(data?.datePublished) ?? toDate(page.date);
+	const dateModified =
+		toDate(data?.dateModified) ??
+		toDate(page.inputPath ? gitLookup(page.inputPath) : null) ??
+		datePublished;
+	return { datePublished, dateModified };
+}

package/core/locale/derive-lang.js

@@ -0,0 +1,19 @@
+/**
+ * Extract the short language subtag from a BCP 47 tag.
+ *
+ * `'en-US'` → `'en'`, `'zh-Hant-HK'` → `'zh'`. Normalises via `Intl.Locale`;
+ * null for empty input or tags it rejects.
+ *
+ * @param {unknown} locale
+ * @returns {string | null}
+ */
+export function deriveLang(locale) {
+	if (locale == null) return null;
+	const str = String(locale).trim();
+	if (str === '') return null;
+	try {
+		return new Intl.Locale(str).language;
+	} catch {
+		return null;
+	}
+}

package/core/locale/index.js

@@ -0,0 +1,6 @@
+export { normalizeLang } from './normalize-lang.js';
+export { normalizeLocale } from './normalize-locale.js';
+export { deriveLang } from './derive-lang.js';
+export { resolveDefault } from './resolve-default.js';
+export { resolveLocale } from './resolve-locale.js';
+export { toOpenGraphLocale } from './open-graph-locale.js';

package/core/locale/normalize-lang.js

@@ -0,0 +1,13 @@
+/**
+ * Normalize a short language code: lowercase and trim.
+ *
+ * The substrate's lightest helper. Empty string for null/undefined; coerces
+ * non-string input via `String()`.
+ *
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function normalizeLang(raw) {
+	if (raw == null) return '';
+	return String(raw).toLowerCase().trim();
+}

package/core/locale/normalize-locale.js

@@ -0,0 +1,20 @@
+/**
+ * Normalize a BCP 47 locale tag to conventional casing using `Intl.Locale`.
+ *
+ * `Intl.Locale` handles language-script-region casing and subtag rules without
+ * reimplementing the spec. Returns null for empty/whitespace input or tags it
+ * rejects.
+ *
+ * @param {unknown} raw
+ * @returns {string | null}
+ */
+export function normalizeLocale(raw) {
+	if (raw == null) return null;
+	const str = String(raw).trim();
+	if (str === '') return null;
+	try {
+		return new Intl.Locale(str).toString();
+	} catch {
+		return null;
+	}
+}

package/core/locale/open-graph-locale.js

@@ -0,0 +1,14 @@
+import { normalizeLocale } from './normalize-locale.js';
+
+/**
+ * Format a BCP 47 tag in Open Graph's `language_TERRITORY` form (`en-US` →
+ * `en_US`). Normalises casing first; null for tags `Intl.Locale` rejects.
+ * `replaceAll` so script+region tags convert fully (`zh-Hant-HK` → `zh_Hant_HK`).
+ *
+ * @param {unknown} raw  A BCP 47 locale tag.
+ * @returns {string | null}
+ */
+export function toOpenGraphLocale(raw) {
+	const normalized = normalizeLocale(raw);
+	return normalized ? normalized.replaceAll('-', '_') : null;
+}

package/core/locale/resolve-default.js

@@ -0,0 +1,27 @@
+import { normalizeLang } from './normalize-lang.js';
+import { normalizeLocale } from './normalize-locale.js';
+import { deriveLang } from './derive-lang.js';
+
+/**
+ * Resolve the effective `{ lang, locale }` default from settings.
+ *
+ * defaultLocale wins; defaultLanguage is a writer-side alias. Given only
+ * defaultLanguage, locale is derived via `Intl.Locale`.
+ *
+ * @param {{ defaultLanguage?: string, defaultLocale?: string }} settings
+ * @returns {{ lang: string, locale: string | null }}
+ */
+export function resolveDefault(settings) {
+	const explicitLang = normalizeLang(settings?.defaultLanguage);
+	const explicitLocale = normalizeLocale(settings?.defaultLocale);
+
+	if (explicitLocale) {
+		return { lang: deriveLang(explicitLocale) ?? explicitLang, locale: explicitLocale };
+	}
+
+	if (explicitLang) {
+		return { lang: explicitLang, locale: normalizeLocale(explicitLang) ?? explicitLang };
+	}
+
+	return { lang: '', locale: null };
+}

package/core/locale/resolve-locale.js

@@ -0,0 +1,16 @@
+/**
+ * Pick the page's BCP 47 locale out of the cascade.
+ *
+ * Reads, never normalises — trusts multilang's already-resolved `page.locale`
+ * first, then bag-level locale, the language's configured locale, and the bare
+ * `lang` tag last.
+ *
+ * @param {{ locale?: string } | undefined} node  The navigator node, if any.
+ * @param {Record<string, any>} data  The Eleventy cascade data bag.
+ * @param {{ languages?: Record<string, { locale?: string }> } | undefined} settings
+ * @param {string} lang  Resolved language subtag; the final fallback.
+ * @returns {string}
+ */
+export function resolveLocale(node, data, settings, lang) {
+	return node?.locale || data?.page?.locale || data?.locale || settings?.languages?.[lang]?.locale || lang;
+}

package/core/markdown/wikilinks.js

@@ -88,7 +88,7 @@ export function wikilinks(md, { slugIndex, pageContextRegistry, translationMapSt
 		}
 
 		const lang = rawLang.toLowerCase();
-		const translationKey = ctx?.page?.locale?.translationKey;
+		const translationKey = ctx?.page?.translationKey;
 		if (!translationKey) return null;
 
 		const map = translationMapStore?.get?.();