@allons-y/webc-patterns 0.1.0-beta.0 → 0.1.0-beta.1

package/markdown.js

@@ -0,0 +1,278 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/*
+ * The Markdown add-on. Each amend turns Markdown into the markup an author would write by hand for the same component.
+ * None writes a string of its own: the component's slot fallbacks and `componentStrings` supply every text.
+ */
+
+/** A custom element's name: a hyphen makes it a component, so ordinary HTML keeps CommonMark's rules. */
+const NAME = String.raw`[a-z][a-z0-9]*-[a-z0-9._-]*`;
+/** An attribute with any name WebC reads (`@variant`, `:@level`, `webc:if`), and an optional value. */
+const ATTR = String.raw`\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>\x60]+))?`;
+const OPEN = new RegExp(String.raw`^<${NAME}(?:${ATTR})*\s*\/?>`, "i");
+const CLOSE = new RegExp(String.raw`^<\/${NAME}\s*>`, "i");
+const TAG_LINE = new RegExp(String.raw`^(?:<${NAME}(?:${ATTR})*\s*\/?>|<\/${NAME}\s*>)\s*$`, "i");
+/** A `<script>` or `<link>` open tag without `webc:keep`. */
+const EMBED = /<(script|link)(?=[\s/>])(?![^>]*\swebc:keep\b)/gi;
+
+/**
+ * markdown-it amend: a component tag stays raw HTML with WebC's attribute names, so `<norn-callout @variant="tip">` reaches WebC as written.
+ * CommonMark's attribute names have no `@`, so markdown-it escapes such a tag to text without it.
+ * A line that is only a component's open or close tag starts an HTML block that runs to the next blank line, as CommonMark's own do; a tag inside a paragraph stays inline.
+ * Fences and code spans stay literal. It does nothing when the library's `html` option is off.
+ * A `<script>` or `<link>` in Markdown is written for the browser, so it gets `webc:keep`: WebC then leaves it in place instead of bundling it, or failing on a full URL or a site path.
+ *
+ * @param {import("markdown-it").default} md
+ */
+export function webcTags(md) {
+	if (!md.options.html) return;
+	md.block.ruler.before(
+		"html_block",
+		"webc_block",
+		(state, startLine, endLine, silent) => {
+			if (state.sCount[startLine] - state.blkIndent >= 4) return false;
+			const line = state.src.slice(state.bMarks[startLine] + state.tShift[startLine], state.eMarks[startLine]);
+			if (!TAG_LINE.test(line)) return false;
+			// Like CommonMark's HTML block of type 7, it can't interrupt a paragraph.
+			if (silent) return false;
+			let next = startLine + 1;
+			while (next < endLine && !state.isEmpty(next)) next++;
+			state.line = next;
+			const token = state.push("html_block", "", 0);
+			token.map = [startLine, next];
+			token.content = state.getLines(startLine, next, state.blkIndent, true);
+			return true;
+		},
+		{ alt: ["paragraph", "reference", "blockquote"] },
+	);
+	for (const type of ["html_block", "html_inline"]) {
+		const render = md.renderer.rules[type];
+		md.renderer.rules[type] = (tokens, index, ...rest) => render(tokens, index, ...rest).replace(EMBED, "<$1 webc:keep");
+	}
+	md.inline.ruler.before("html_inline", "webc_inline", (state, silent) => {
+		if (state.src.charCodeAt(state.pos) !== 0x3c) return false;
+		const rest = state.src.slice(state.pos);
+		const match = OPEN.exec(rest) ?? CLOSE.exec(rest);
+		if (!match) return false;
+		if (!silent) state.push("html_inline", "", 0).content = match[0];
+		state.pos += match[0].length;
+		return true;
+	});
+}
+
+/**
+ * markdown-it amend: wrap each Markdown table in `<norn-simple-table>`, so a wide one scrolls in its own box.
+ *
+ * @param {import("markdown-it").default} md
+ */
+export function scrollTables(md) {
+	const render = (tokens, index, options, env, self) => self.renderToken(tokens, index, options);
+	const open = md.renderer.rules.table_open ?? render;
+	const close = md.renderer.rules.table_close ?? render;
+	md.renderer.rules.table_open = (...args) => `<norn-simple-table>${open(...args)}`;
+	md.renderer.rules.table_close = (...args) => `${close(...args)}</norn-simple-table>\n`;
+}
+
+const CALLOUT = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*/i;
+
+/**
+ * markdown-it amend: a blockquote that opens with `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!CAUTION]` renders as `<norn-callout>`, as on GitHub.
+ * It writes no title: the component's `heading` slot falls back to the site's `componentStrings`, then English.
+ *
+ * @param {import("markdown-it").default} md
+ */
+export function callouts(md) {
+	md.core.ruler.push("callouts", (state) => {
+		const { tokens } = state;
+		for (let index = 0; index < tokens.length; index++) {
+			const open = tokens[index];
+			const inline = tokens[index + 2];
+			if (open.type !== "blockquote_open" || tokens[index + 1]?.type !== "paragraph_open" || inline?.type !== "inline") continue;
+			const marker = CALLOUT.exec(inline.content);
+			if (!marker) continue;
+			const variant = marker[1].toLowerCase();
+			inline.content = inline.content.slice(marker[0].length);
+			const [first, second] = inline.children;
+			first.content = first.content.replace(CALLOUT, "");
+			if (!first.content) inline.children.splice(0, second?.type === "softbreak" ? 2 : 1);
+			if (!inline.children.length) tokens[index + 1].hidden = tokens[index + 3].hidden = true;
+			open.meta = { ...open.meta, callout: variant };
+			for (let depth = 0, close = index; close < tokens.length; close++) {
+				depth += tokens[close].nesting * (tokens[close].type.startsWith("blockquote") ? 1 : 0);
+				if (tokens[close].type === "blockquote_close" && depth === 0) {
+					tokens[close].meta = { ...tokens[close].meta, callout: variant };
+					break;
+				}
+			}
+		}
+	});
+	const render = (tokens, index, options, env, self) => self.renderToken(tokens, index, options);
+	const callout = (variant) => `<norn-callout @variant="${variant}">\n`;
+	const open = md.renderer.rules.blockquote_open ?? render;
+	const close = md.renderer.rules.blockquote_close ?? render;
+	md.renderer.rules.blockquote_open = (tokens, index, ...rest) => (tokens[index].meta?.callout ? callout(tokens[index].meta.callout) : open(tokens, index, ...rest));
+	md.renderer.rules.blockquote_close = (tokens, index, ...rest) => (tokens[index].meta?.callout ? "</norn-callout>\n" : close(tokens, index, ...rest));
+}
+
+/** Text for comparing titles: spaces collapsed, case folded. */
+const titleText = (text) => String(text).replace(/\s+/g, " ").trim().toLowerCase();
+
+/**
+ * markdown-it amend: on a layout that shows the page title as its h1, keep the page to one h1.
+ * A leading `# Title` that repeats the title goes, and any other h1 becomes an h2, which `headingAnchors` then anchors.
+ * The layout is the page's own `layout`, by name; the title is the layout's, `norn.title`, or else the page's `title`.
+ *
+ * @param {import("markdown-it").default} md
+ * @param {{ layouts?: string[] }} [options] - Layouts that show the title as an h1. Defaults to `norn-docs` and `norn-workspace`.
+ */
+export function singleTitle(md, { layouts = ["norn-docs", "norn-workspace"] } = {}) {
+	const rule = (state) => {
+		const env = state.env && typeof state.env === "object" ? state.env : {};
+		const layout = String(env.layout ?? "").split("/").pop().replace(/\.webc$/, "");
+		if (!layouts.includes(layout)) return;
+		const title = env.norn?.workspace?.name ?? env.norn?.title ?? env.title;
+		const { tokens } = state;
+		const text = (inline) => inline.children.filter((child) => child.type === "text" || child.type === "code_inline").map((child) => child.content).join("");
+		if (tokens[0]?.type === "heading_open" && tokens[0].tag === "h1" && typeof title === "string" && titleText(text(tokens[1])) === titleText(title)) tokens.splice(0, 3);
+		for (const token of tokens) {
+			if ((token.type === "heading_open" || token.type === "heading_close") && token.tag === "h1") {
+				token.tag = "h2";
+				token.markup = "##";
+			}
+		}
+	};
+	// It runs before the anchors, so a demoted heading gets one.
+	if (md.core.ruler.__find__("heading_anchors") === -1) md.core.ruler.push("single_title", rule);
+	else md.core.ruler.before("heading_anchors", "single_title", rule);
+}
+
+/**
+ * A URL fragment from heading text: the letters, marks, and digits of any script, lowercase, with accents off Latin letters, and runs of anything else as one hyphen.
+ * An ASCII heading keeps the id it always had.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export const slugify = (text) =>
+	String(text)
+		.normalize("NFKD")
+		.toLowerCase()
+		.replace(/(?<=\p{Script=Latin})\p{M}+/gu, "")
+		.normalize("NFC")
+		.replace(/[^\p{L}\p{M}\p{N}]+/gu, "-")
+		.replace(/^-|-$/g, "") || "section";
+
+/** Ids taken so far, by page: Eleventy hands each Markdown render of a page, such as two Markdown blocks, the same `page` object, and a new one each build. Without a page, by render. */
+const taken = new WeakMap();
+
+/**
+ * The ids given so far on the page this render belongs to.
+ *
+ * @param {object} env - The render's environment: Eleventy's page data
+ * @returns {Set<string>}
+ */
+function idsOf(env) {
+	const key = env?.page && typeof env.page === "object" ? env.page : env && typeof env === "object" ? env : {};
+	if (!taken.has(key)) taken.set(key, new Set());
+	return taken.get(key);
+}
+
+/**
+ * markdown-it amend: give each heading at the chosen levels an id, and render it as `norn-heading-anchor`, as an author writes it, so its text links to itself.
+ * A repeated heading gets `-2`, `-3`, and so on, counted across the page. A heading that already has an id keeps it.
+ * A heading whose text holds a link gets the id only, so no link nests in another. So does an h1, which the component has no tag for.
+ *
+ * @param {import("markdown-it").default} md
+ * @param {{ levels?: number[] }} [options] - Heading levels to anchor. Defaults to 2 and 3.
+ */
+export function headingAnchors(md, { levels = [2, 3] } = {}) {
+	md.core.ruler.push("heading_anchors", (state) => {
+		const ids = idsOf(state.env);
+		state.tokens.forEach((token, index) => {
+			const level = Number(token.tag.slice(1));
+			if (token.type !== "heading_open" || !levels.includes(level)) return;
+			const inline = state.tokens[index + 1];
+			let id = token.attrGet("id");
+			if (!id) {
+				const base = slugify(inline.children.filter((child) => child.type === "text" || child.type === "code_inline").map((child) => child.content).join(""));
+				id = base;
+				for (let count = 2; ids.has(id); count++) id = `${base}-${count}`;
+				token.attrSet("id", id);
+			}
+			ids.add(id);
+			// A link can't hold a link: a heading whose text links elsewhere keeps the author's link and takes only the id.
+			if (level < 2 || inline.children.some((child) => child.type === "link_open")) return;
+			const anchor = { slug: id, level };
+			token.meta = { ...token.meta, anchor };
+			const close = state.tokens.slice(index).find((next) => next.type === "heading_close");
+			close.meta = { ...close.meta, anchor };
+		});
+	});
+	const render = (tokens, index, options, env, self) => self.renderToken(tokens, index, options);
+	const open = md.renderer.rules.heading_open ?? render;
+	const close = md.renderer.rules.heading_close ?? render;
+	md.renderer.rules.heading_open = (tokens, index, ...rest) => {
+		const anchor = tokens[index].meta?.anchor;
+		if (!anchor) return open(tokens, index, ...rest);
+		return `<norn-heading-anchor @slug="${md.utils.escapeHtml(anchor.slug)}"${anchor.level === 2 ? "" : ` :@level="${anchor.level}"`}>`;
+	};
+	md.renderer.rules.heading_close = (tokens, index, ...rest) => (tokens[index].meta?.anchor ? "</norn-heading-anchor>\n" : close(tokens, index, ...rest));
+}
+
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", apos: "'" };
+
+/** Markup as plain text: tags off, the common entities decoded, spaces collapsed. */
+const plain = (markup) =>
+	markup
+		.replace(/<[^>]+>/g, "")
+		.replace(/&(amp|lt|gt|quot|#39|apos);/g, (_, name) => ENTITIES[name])
+		.replace(/\s+/g, " ")
+		.trim();
+
+/** A heading with an id, as compiled or written as HTML. */
+const HEADING = /<h([1-6])\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/h\1>/g;
+/** `norn-heading-anchor` before WebC compiles it: as `headingAnchors` writes it, or as an author does in Markdown. */
+const ANCHOR = new RegExp(String.raw`<norn-heading-anchor\b((?:${ATTR})*)\s*>([\s\S]*?)<\/norn-heading-anchor>`, "g");
+
+/**
+ * A prop of an uncompiled tag: `@name="x"`, `name="x"`, or `:@name` with a string or number literal.
+ *
+ * @param {string} attributes
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function prop(attributes, name) {
+	const match = new RegExp(String.raw`(?:^|\s)(:?@?)${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`).exec(attributes);
+	if (!match) return undefined;
+	const value = (match[2] ?? match[3]).replace(/&(amp|lt|gt|quot|#39|apos);/g, (_, entity) => ENTITIES[entity]);
+	if (match[1] !== ":@") return value;
+	const literal = /^\s*(?:'([^']*)'|"([^"]*)"|(\d+))\s*$/.exec(value);
+	return literal ? (literal[1] ?? literal[2] ?? literal[3]) : undefined;
+}
+
+/**
+ * The headings in rendered HTML that carry an id, for `norn-toc`, in page order.
+ * It reads a heading with an id, and a `norn-heading-anchor` that WebC has not compiled yet, as `headingAnchors` writes it in Markdown.
+ *
+ * @param {string} html
+ * @param {{ levels?: number[] }} [options] - Heading levels to list. Defaults to 2 and 3.
+ * @returns {{ id: string, text: string, level: number }[]}
+ */
+export function headings(html, { levels = [2, 3] } = {}) {
+	if (typeof html !== "string") return [];
+	const found = [...html.matchAll(HEADING)].map((match) => ({ at: match.index, id: match[2], level: Number(match[1]), text: plain(match[3]) }));
+	for (const match of html.matchAll(ANCHOR)) {
+		const id = prop(match[1], "slug");
+		// A compiled anchor has no slug on its tag: the heading inside it is listed above.
+		if (id) found.push({ at: match.index, id, level: Number(prop(match[1], "level") ?? 2) || 2, text: plain(match[2]) });
+	}
+	return found
+		.filter((heading) => levels.includes(heading.level))
+		.sort((a, b) => a.at - b.at)
+		.map(({ id, level, text }) => ({ id, level, text }));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@allons-y/webc-patterns",
-	"version": "0.1.0-beta.0",
-	"description": "Generic WebC page and docs patterns for Eleventy sites: head, header, footer, hero, card, side nav, docs shell, and pager.",
+	"version": "0.1.0-beta.1",
+	"description": "Generic WebC components and Eleventy layouts for page and docs sites, with the Norn plugin that registers them: header, footer, hero, cards, side nav, docs shell, and pager.",
 	"license": "MPL-2.0",
 	"author": "Cassondra Roberts <castastrophe@users.noreply.github.com> (https://allons-y.studio)",
 	"homepage": "https://github.com/allonsy-studio/webc-resources/tree/main/packages/webc-patterns#readme",
@@ -20,17 +20,46 @@
 	"type": "module",
 	"exports": {
 		".": "./index.js",
+		"./markdown": "./markdown.js",
+		"./plugin": "./plugin.js",
+		"./project": "./project.js",
+		"./css/reset.css": "./css/reset.css",
+		"./css/base.css": "./css/base.css",
+		"./css/print.css": "./css/print.css",
+		"./schema/project.schema.json": "./schema/project.schema.json",
 		"./package.json": "./package.json"
 	},
 	"files": [
 		"components/",
+		"layouts/",
+		"fallback/",
+		"css/",
+		"lib/",
+		"schema/",
 		"index.js",
+		"markdown.js",
+		"plugin.js",
+		"project.js",
 		"LICENSE",
 		"README.md"
 	],
+	"scripts": {
+		"prepack": "node ../../scripts/build-components.js webc-patterns"
+	},
+	"dependencies": {
+		"hosted-git-info": "^10.1.1",
+		"markdown-it": "^15.0.2",
+		"semver": "^7.8.5"
+	},
 	"peerDependencies": {
 		"@11ty/eleventy": "^3.0.0",
-		"@11ty/eleventy-plugin-webc": "^0.11.0"
+		"@11ty/eleventy-plugin-webc": "^0.11.0",
+		"@allons-y/webc-code-sample": "^0.1.0-beta.0"
+	},
+	"peerDependenciesMeta": {
+		"@allons-y/webc-code-sample": {
+			"optional": true
+		}
 	},
 	"keywords": [
 		"webc",

package/plugin.js

@@ -0,0 +1,279 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import webc from "@11ty/eleventy-plugin-webc";
+
+import { adjacent, componentStrings, dropEmptyBundleTags, patterns } from "./index.js";
+import { readIcons } from "./lib/icons.js";
+import { isInstalled } from "./lib/optional.js";
+import { callouts, headingAnchors, headings, scrollTables, singleTitle, webcTags } from "./markdown.js";
+
+const HERE = import.meta.dirname;
+const posix = (file) => file.split(path.sep).join("/");
+
+/** Absolute path to the optional reset, `css/reset.css`, in the `norn.reset` layer. Norn looks the same without it. */
+export const reset = posix(path.join(HERE, "css", "reset.css"));
+
+/** Absolute path to the base styles, `css/base.css`, that `norn-base` embeds. For a layout of the project's own. */
+export const base = posix(path.join(HERE, "css", "base.css"));
+
+/** Absolute path to the print styles, `css/print.css`, that `norn-base` embeds. For a layout of the project's own. */
+export const print = posix(path.join(HERE, "css", "print.css"));
+
+/** The places in `norn-base` a theme or project fills with markup, in page order. */
+export const HOOKS = Object.freeze(["head", "banner", "cta", "credit"]);
+
+/** The layouts the plugin ships. Every one but `norn-base` extends `norn-base`. */
+export const LAYOUTS = Object.freeze(["norn-base", "norn-docs", "norn-docs-home", "norn-landing", "norn-workspace", "norn-workspaces-home"]);
+
+/** The props `norn-base` and the layouts read, looked up on the page data by name when there is no `props` mapping. */
+const PROPS = [
+	"lang",
+	"dir",
+	"title",
+	"name",
+	"tagline",
+	"description",
+	"url",
+	"ogTitle",
+	"ogImage",
+	"locale",
+	"themeColor",
+	"themeToggle",
+	"icon",
+	"touchIcon",
+	"logo",
+	"nav",
+	"footer",
+	"lede",
+	"install",
+	"repo",
+	"license",
+	"node",
+	"usage",
+	"features",
+	"packages",
+	"docs",
+	"prev",
+	"next",
+	"search",
+	"workspaces",
+	"workspace",
+];
+
+/** The props that are lists: each defaults to `[]`, so a layout can loop over it. */
+const LISTS = ["nav", "features", "packages", "docs", "workspaces"];
+
+/** Icon types by file extension, for the icon link. */
+const ICON_TYPES = { ".svg": "image/svg+xml", ".png": "image/png", ".ico": "image/x-icon", ".webp": "image/webp" };
+
+/** The plain `norn-code-block`, `<pre><code>`, registered in place of the code sample when it is not installed. */
+const plainCodeBlock = posix(path.join(HERE, "fallback", "norn-code-block.webc"));
+
+/**
+ * `@allons-y/webc-code-sample`, when it is installed: an optional peer. Without it the plugin registers `plainCodeBlock` under the same tag.
+ * Any other failure to load it is a real error and is thrown.
+ */
+const codeSample = isInstalled("@allons-y/webc-code-sample")
+	? await Promise.all([import("@allons-y/webc-code-sample"), import("@allons-y/webc-code-sample/markdown")]).then(([main, markdown]) => ({
+		codeBlock: main.codeBlock,
+		tokenRanges: main.tokenRanges,
+		highlightFences: markdown.highlightFences,
+	}))
+	: null;
+
+/** Per-configuration state: the hook fills, and whether the plugin ran. */
+const states = new WeakMap();
+
+function state(config) {
+	if (!states.has(config)) states.set(config, { hooks: Object.fromEntries(HOOKS.map((name) => [name, []])), registered: false });
+	return states.get(config);
+}
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const list = (value) => (Array.isArray(value) ? value : []);
+const defined = (object) => Object.fromEntries(Object.entries(isObject(object) ? object : {}).filter(([, value]) => value !== undefined));
+
+/**
+ * Add markup to the hooks in `norn-base`: `head` (end of the head), `banner` (before the header), `cta` (end of `main`), and `credit` (the footer's last column).
+ * A fill is WebC markup, compiled with the page, so it may call components. Fills are appended in the order they are added, and no page data can change them.
+ * Themes call it from their plugin, and projects from their config: a favicon, a project stylesheet.
+ *
+ * @param {import("@11ty/eleventy").UserConfig} config
+ * @param {{ head?: string, banner?: string, cta?: string, credit?: string }} fills - Markup by hook name
+ * @throws {Error} On an unknown hook name, or a fill that is not a string
+ */
+export function fillHooks(config, fills = {}) {
+	const { hooks } = state(config);
+	for (const [name, markup] of Object.entries(fills)) {
+		if (!HOOKS.includes(name)) throw new Error(`norn: no hook named "${name}". Hooks: ${HOOKS.join(", ")}`);
+		if (typeof markup !== "string") throw new Error(`norn: the ${name} hook takes a markup string.`);
+		hooks[name].push(markup);
+	}
+}
+
+/** The props a page reads off its own data when the project gives no mapping: the same-named fields. */
+const sameNamed = (data) => Object.fromEntries(PROPS.map((key) => [key, data?.[key]]));
+
+/**
+ * The layout props for one page, from the mapping or the same-named page data, over the theme's defaults.
+ * It runs against Eleventy's placeholder data too, so it never throws on missing data, and every list is a list.
+ *
+ * @param {object} data - The page data
+ * @param {(data: object) => object} map
+ * @param {object} defaults
+ */
+function layoutProps(data, map, defaults) {
+	const props = { ...defined(defaults), ...defined(map(data)) };
+	props.lang = typeof props.lang === "string" && props.lang ? props.lang : typeof data?.page?.lang === "string" && data.page.lang ? data.page.lang : "en";
+	for (const key of LISTS) props[key] = list(props[key]);
+	const footer = defined(props.footer);
+	props.footer = { ...footer, badges: list(footer.badges), groups: list(footer.groups).map((group) => ({ ...defined(group), links: list(group?.links) })) };
+	if (typeof props.icon === "string") props.icon = { href: props.icon };
+	if (isObject(props.icon) && typeof props.icon.href === "string") {
+		props.icon = { ...props.icon, type: props.icon.type ?? ICON_TYPES[path.extname(props.icon.href).toLowerCase()] ?? "image/png" };
+	} else {
+		delete props.icon;
+	}
+	if (typeof props.logo === "string") props.logo = { src: props.logo };
+	if (!isObject(props.logo) || typeof props.logo.src !== "string") delete props.logo;
+	if (typeof props.ogImage === "string") props.ogImage = { src: props.ogImage };
+	if (!isObject(props.ogImage) || typeof props.ogImage.src !== "string" || !props.ogImage.src) delete props.ogImage;
+	return props;
+}
+
+/**
+ * Whether a shipped layout compiles the page content as WebC, so the components the Markdown add-ons write render: the `nornCompiles` helper.
+ * Content compiles exactly once, and only when it is Markdown output that no WebC has compiled, by `page.templateSyntax`.
+ * WebC output, a `templateEngineOverride` with `webc`, and a Nunjucks or Liquid page that renders through `{% renderTemplate "webc" %}` are already compiled.
+ * A project's own WebC layout as the page's layout compiles the content itself. A Nunjucks or Liquid layout in the chain, or a layout alias, does not.
+ * Every child layout sets `nornCompiled: true` in its front matter, which reaches `norn-base` in the data, so the frame leaves what the child compiled.
+ *
+ * @param {object} data - The page data, `$data`
+ * @param {string} layout - The shipped layout that asks, such as `norn-docs`
+ * @param {Record<string, string>} [aliases] - The project's layout aliases
+ * @returns {boolean}
+ */
+export function compiles(data, layout, aliases = {}) {
+	const engines = String(data?.page?.templateSyntax ?? "").split(",");
+	if (!engines.includes("md") || engines.includes("webc")) return false;
+	const own = String(aliases[data.layout] ?? data.layout ?? "");
+	if (own.endsWith(".webc") && !LAYOUTS.includes(path.posix.basename(own, ".webc"))) return false;
+	return layout !== "norn-base" || !data.nornCompiled;
+}
+
+/** Read a compiled layout, with `norn-base`'s style placeholders filled from the package's css folder. */
+function readLayout(name) {
+	const text = fs.readFileSync(path.join(HERE, "layouts", `${name}.webc`), "utf8");
+	return text.replace(/\/\* norn: css\/(base|print)\.css \*\//g, (_, file) => fs.readFileSync(path.join(HERE, "css", `${file}.css`), "utf8").trim());
+}
+
+/**
+ * The Norn plugin for Eleventy: the one `@11ty/eleventy-plugin-webc` registration, the layouts, the helpers, and the Markdown add-ons.
+ *
+ * @param {import("@11ty/eleventy").UserConfig} config
+ * @param {object} [options]
+ * @param {(data: object) => object} [options.props] - Maps a page's data to the layout props, added as `eleventyComputed.norn`. Without it, each prop is read off the same-named page data. It runs against Eleventy's placeholder data too: it must not throw on missing data.
+ * @param {boolean | string[]} [options.layouts] - `true` ships the six layouts, `false` none, or a list of layout names to leave out, so the project can supply its own
+ * @param {string[]} [options.components] - More component globs: a theme's, the project's
+ * @param {string[]} [options.exclude] - Packaged components to leave out, so the project can supply its own
+ * @param {Record<string, object>} [options.strings] - The `componentStrings` table, registered as `nornComponentStrings`
+ * @param {string | string[] | Record<string, string | { src: string, mirror?: boolean }>} [options.icons] - Project icons for `norn-icon`: a glob or list of globs of `.svg` files, each named for its file without the extension, or a record of names to a path or `{ src, mirror }`. Paths resolve against the working directory. A name that matches a built-in icon replaces it
+ * @param {boolean} [options.markdown] - Amend Markdown with the add-ons: component tags with WebC attributes kept as HTML, fenced code as `norn-code-block` when the code sample is installed, callouts, scrolling tables, one h1 on a layout that shows the title, and anchored headings. On by default
+ * @param {object} [options.defaults] - Prop values a theme sets, under the mapping's
+ * @throws {Error} On a bad option, a missing icon file, a second registration of the plugin or of `@11ty/eleventy-plugin-webc`, or, at build time, a project layout named like a shipped one or a page that sets the reserved `norn` key
+ */
+export default function norn(config, options = {}) {
+	const { props, layouts = true, components = [], exclude = [], strings = {}, markdown = true, defaults = {}, icons } = options ?? {};
+	if (props !== undefined && typeof props !== "function") throw new Error("norn: `props` must be a function from page data to layout props.");
+	if (!Array.isArray(components) || components.some((glob) => typeof glob !== "string")) throw new Error("norn: `components` must be a list of globs.");
+	if (layouts !== true && layouts !== false && !Array.isArray(layouts)) throw new Error("norn: `layouts` must be true, false, or a list of layout names to leave out.");
+	const skipped = Array.isArray(layouts) ? layouts.map((name) => String(name).replace(/\.webc$/, "")) : [];
+	const unknown = skipped.filter((name) => !LAYOUTS.includes(name));
+	if (unknown.length) throw new Error(`norn: no layout named ${unknown.map((name) => `"${name}"`).join(", ")}. Layouts: ${LAYOUTS.join(", ")}`);
+
+	let projectIcons = readIcons(icons);
+
+	const own = state(config);
+	if (own.registered) throw new Error("norn: the plugin is added twice. A theme such as @allons-y/webc-oss-site adds it for you: add the theme in its place.");
+	own.registered = true;
+
+	if (config.plugins?.some((entry) => entry.plugin === webc)) {
+		throw new Error("norn: @11ty/eleventy-plugin-webc is registered twice. The Norn plugin registers it: remove the project's own `addPlugin`, and pass its component globs as `components`.");
+	}
+	try {
+		config.addPlugin(webc, { components: [patterns({ exclude }), codeSample ? codeSample.codeBlock : plainCodeBlock, ...components] });
+	} catch (error) {
+		if (/"webc" template syntax twice/.test(error.message)) {
+			throw new Error("norn: @11ty/eleventy-plugin-webc is registered twice. The Norn plugin registers it: remove the other `addPlugin`, and pass its component globs as `components`.", { cause: error });
+		}
+		throw error;
+	}
+
+	config.addJavaScriptFunction("nornAdjacent", adjacent);
+	config.addJavaScriptFunction("nornHeadings", headings);
+	config.addJavaScriptFunction("nornComponentStrings", componentStrings(strings));
+	config.addJavaScriptFunction("nornHook", (name) => {
+		if (!HOOKS.includes(name)) throw new Error(`norn: no hook named "${name}". Hooks: ${HOOKS.join(", ")}`);
+		return own.hooks[name].join("\n");
+	});
+	config.addJavaScriptFunction("nornIcons", () => projectIcons);
+	config.addJavaScriptFunction("nornCompiles", (data, layout) => compiles(data, layout, config.layoutAliases ?? {}));
+	if (icons !== undefined) {
+		config.on("eleventy.before", () => {
+			projectIcons = readIcons(icons);
+		});
+		for (const glob of [icons].flat()) if (typeof glob === "string") config.addWatchTarget?.(glob);
+		if (isObject(icons)) for (const value of Object.values(icons)) config.addWatchTarget?.(typeof value === "string" ? value : value.src);
+	}
+	if (codeSample) config.addJavaScriptFunction("nornTokenRanges", codeSample.tokenRanges);
+
+	if (markdown) {
+		config.amendLibrary("md", webcTags);
+		if (codeSample) config.amendLibrary("md", codeSample.highlightFences);
+		config.amendLibrary("md", scrollTables);
+		config.amendLibrary("md", callouts);
+		config.amendLibrary("md", singleTitle);
+		config.amendLibrary("md", headingAnchors);
+	}
+
+	config.addTransform("norn-empty-bundle-tags", dropEmptyBundleTags);
+
+	const map = props ?? sameNamed;
+	config.addGlobalData("eleventyComputed", { norn: (data) => layoutProps(data, map, defaults) });
+	// A preprocessor sees the data before computed data runs, so a page's own `norn` is still there to report.
+	config.addPreprocessor("norn-reserved", "*", (data) => {
+		if (data?.norn !== undefined) throw new Error(`norn: ${data.page?.inputPath} sets \`norn\`, a reserved key: the plugin computes it from \`props\`, which would replace it. Map the value in \`props\`, or rename the key.`);
+	});
+
+	if (layouts === false) return;
+	const shipped = LAYOUTS.filter((name) => !skipped.includes(name));
+	const dirs = config.directories;
+	const input = path.posix.normalize(dirs.input);
+	const strays = new Set();
+	for (const name of shipped) {
+		// Eleventy looks a layout up by its path relative to the input folder, and lists a virtual one outside it as a page too.
+		const file = path.posix.normalize(path.posix.join(dirs.layouts ?? dirs.includes, `${name}.webc`));
+		const key = file.startsWith(input) && input !== "./" ? file.slice(input.length) : file;
+		config.addTemplate(key, readLayout(name), {});
+		strays.add(`./${path.posix.join(input, key)}`);
+	}
+	config.addPreprocessor("norn-layouts", "webc", function () {
+		if (strays.has(this.inputPath)) return false;
+	});
+
+	config.on("eleventy.before", () => {
+		const folders = [...new Set([dirs.includes, dirs.layouts].filter(Boolean))];
+		const found = folders.flatMap((folder) => shipped.map((name) => path.join(folder, `${name}.webc`))).filter((file) => fs.existsSync(file));
+		if (found.length) {
+			throw new Error(`norn: ${found.map(posix).join(", ")} has the name of a shipped layout, which would silently replace the file. Rename it, or leave the shipped one out with \`layouts: [${found.map((file) => `"${path.basename(file, ".webc")}"`).join(", ")}]\`.`);
+		}
+	});
+}

package/project.js

@@ -0,0 +1,15 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/*
+ * Optional data builders for a project site: facts from package.json and project.json, one entry per workspace, the npm release check,
+ * and the accent for badges. A project maps what they return to the layout props through the Norn plugin's `props`.
+ */
+
+export { accentHex, npmRelease } from "./lib/npm.js";
+export { buildSite } from "./lib/site.js";
+export { buildWorkspaces } from "./lib/workspaces.js";