@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/editor-theme-help.mjs

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { getSourcePageLocation } from './source-files.mjs';
+import { selectPageTheme } from './theme-packages.mjs';
+
+const presetHelp = (siteRoot, selection) => {
+	const origin = selection.sourceFiles.findLast((file) => file.config.preset !== undefined);
+	return `Preset: ${selection.selected.config.preset}\nPreset source: ${path.relative(siteRoot, origin.path)}`;
+};
+
+// Cache only within one tree read: dirty buffers and external changes must be
+// reflected on the next refresh. The engine resolver owns all inheritance rules.
+export const createEditorThemeHelp = ({ siteRoot, sources }) => {
+	const selections = new Map();
+	return async (directory, filename) => {
+		const includePageTheme = !filename || path.basename(filename) === 'page-theme.yaml';
+		const key = JSON.stringify([directory, includePageTheme]);
+		if (!selections.has(key)) selections.set(key, selectPageTheme({ siteRoot, sources,
+			pageDirectory: getSourcePageLocation(siteRoot, directory).pageDirectory, includePageTheme })
+			.catch(() => null));
+		const selection = await selections.get(key);
+		if (!selection) return 'Preset unavailable. Check the theme diagnostics.';
+		const file = filename && selection.sourceFiles.find((entry) => entry.path === filename);
+		const mode = !file ? '' : file.config.preset === undefined
+			? 'Modifies inherited settings. Add preset to replace the base.'
+			: getSourcePageLocation(siteRoot, directory).isHome && !includePageTheme
+				? 'Required base for the site. Its preset cannot be omitted.'
+				: 'Replaces inherited settings, even with the same preset name. Remove preset to resume inheritance.';
+		return [presetHelp(siteRoot, selection), mode].filter(Boolean).join('\n');
+	};
+};
+
+export const getEditorThemeRemovalHelp = async ({ siteRoot, filename, sources }) => {
+	const afterRemoval = new Map(sources);
+	afterRemoval.set(filename, null);
+	try {
+		const selection = await selectPageTheme({ siteRoot, sources: afterRemoval,
+			pageDirectory: getSourcePageLocation(siteRoot, path.dirname(filename)).pageDirectory,
+			includePageTheme: false });
+		return `After removal, the inherited tree theme is ${path.relative(siteRoot, selection.treeTheme.path)}.\n${presetHelp(siteRoot, selection)}`;
+	} catch {
+		return 'The inherited preset cannot be determined until the remaining theme errors are repaired.';
+	}
+};

package/scripts/lib/locale-registry.mjs

@@ -562,7 +562,7 @@ const normalizeLanguageTag = (value) => {
 
 const formatSupportedLanguages = () => supportedLocaleTags.join(', ');
 
-export const resolveLocale = (configuredLanguage = 'en', sourceLabel = 'site/config.yaml') => {
+export const resolveLocale = (configuredLanguage = 'en', sourceLabel = 'site/site-config/settings.yaml') => {
 	let parsed;
 	try {
 		parsed = normalizeLanguageTag(configuredLanguage);

package/scripts/lib/locales/en.mjs

@@ -61,7 +61,7 @@ export default Object.freeze({
 	pageSections: 'Sections',
 	previousImage: 'Previous image',
 	previousPage: 'Previous page',
-	returnHome: 'Go to the homepage',
+	returnHome: 'Home',
 	searchReturn: 'Back to {page}',
 	search: 'Search',
 	searchDescription: 'Search the published content on this site.',

package/scripts/lib/logo-assets.mjs

@@ -1,3 +1,4 @@
+import { publicFilePublication } from './publication-paths.mjs';
 import { readdirSync } from 'node:fs';
 import { sitePublicDir, sitePublicLabel } from './site-paths.mjs';
 import {
@@ -23,7 +24,7 @@ export const getPublicAssetInspection = () => inspectPublicAssetFilenames(getPub
 export const getLogoAssets = () => getPublicAssetInspection().logos
 	.map((entry) => ({
 		filename: entry,
-		href: `/${entry}`,
+		href: publicFilePublication(entry).pathname,
 	}));
 
 export const getLogoAsset = () => {

package/scripts/lib/markdown-images.mjs

@@ -0,0 +1,59 @@
+import { getNodeRange, getInlineLinkTargetRange, getDefinitionTargetRange, visitNodes } from './markdown-links.mjs';
+import { managedImageFilenamePattern } from './structured-blocks.mjs';
+
+const filenamePattern = new RegExp(managedImageFilenamePattern);
+
+// Public URLs and remote resources keep their existing rendering rules.
+export const classifyMarkdownImage = (target) => {
+	if (/^(?:[a-z][a-z0-9+.-]*:|\/|#)/i.test(target)) return { kind: 'external' };
+	let decoded;
+	try { decoded = decodeURIComponent(target); } catch { return { kind: 'invalid' }; }
+	const image = decoded.replace(/^(?:\.\/)?images\//, '');
+	return filenamePattern.test(image) ? { kind: 'managed', image } : { kind: 'invalid' };
+};
+
+export const getImageDefinitions = (tree) => {
+	const definitions = new Map();
+	visitNodes(tree, (node) => {
+		if (node.type === 'definition' && !definitions.has(node.identifier)) definitions.set(node.identifier, node);
+	});
+	return definitions;
+};
+
+export const extractMarkdownImageReferences = ({ source, tree, lineOffset = 0 }) => {
+	const definitions = getImageDefinitions(tree);
+	const references = [];
+	visitNodes(tree, (node) => {
+		if (!['image', 'imageReference'].includes(node.type)) return;
+		const destination = node.type === 'image' ? node : definitions.get(node.identifier);
+		if (!destination) return;
+		const target = destination.url ?? '';
+		const classification = classifyMarkdownImage(target);
+		if (classification.kind === 'external') return;
+		const targetRange = node.type === 'image'
+			? getInlineLinkTargetRange(source, node)
+			: getDefinitionTargetRange(source, destination);
+		references.push({
+			...classification,
+			target,
+			alt: node.alt ?? '',
+			title: destination.title,
+			line: lineOffset + (node.position?.start.line ?? 1),
+			blockType: 'markdown-image',
+			blockDisplayType: 'Markdown image',
+			range: getNodeRange(node),
+			targetRange,
+			targetSource: targetRange ? source.slice(targetRange.start, targetRange.end) : target,
+			definitionSource: node.type === 'imageReference' ? source.slice(destination.position.start.offset, destination.position.end.offset) : undefined,
+		});
+	});
+	return references;
+};
+
+export const markdownImageDiagnostic = (reference, label) => ({
+	code: 'invalid-markdown-image',
+	severity: 'error',
+	line: reference.line,
+	message: `${label} line ${reference.line}: Local Markdown image "${reference.target}" must identify a supported file in this page's images/ folder.`,
+	fix: 'Use images/name.jpg (or .jpeg, .png, .svg), with a filename containing letters, numbers, dots or hyphens. Norna also accepts ./images/name.jpg and the bare filename.',
+});

package/scripts/lib/markdown-links.mjs

@@ -1,4 +1,4 @@
-const getNodeRange = (node) => {
+export const getNodeRange = (node) => {
 	const start = node.position?.start.offset;
 	const end = node.position?.end.offset;
 	return Number.isInteger(start) && Number.isInteger(end)
@@ -6,7 +6,7 @@ const getNodeRange = (node) => {
 		: null;
 };
 
-const visitNodes = (node, visit) => {
+export const visitNodes = (node, visit) => {
 	if (!node || typeof node !== 'object') return;
 	visit(node);
 	if (!Array.isArray(node.children)) return;
@@ -55,9 +55,28 @@ const scanDestination = (source, start, end) => {
 	return { start: targetStart, end: cursor };
 };
 
-const getInlineLinkTargetRange = (source, node) => {
+export const getInlineLinkTargetRange = (source, node) => {
 	const nodeRange = getNodeRange(node);
 	if (!nodeRange) return null;
+	if (node.type === 'image') {
+		let depth = 1;
+		for (let cursor = nodeRange.start + 2; cursor < nodeRange.end; cursor += 1) {
+			if (source[cursor] === '\\') { cursor += 1; continue; }
+			if (source[cursor] === '`') {
+				const run = source.slice(cursor).match(/^`+/)[0];
+				const followingRuns = source.slice(cursor + run.length, nodeRange.end).matchAll(/`+/g);
+				const closing = [...followingRuns].find((match) => match[0].length === run.length);
+				if (closing) { cursor += run.length + closing.index + run.length - 1; continue; }
+				cursor += run.length - 1;
+				continue;
+			}
+			if (source[cursor] === '[') depth += 1;
+			if (source[cursor] === ']' && --depth === 0) {
+				return source[cursor + 1] === '(' ? scanDestination(source, cursor + 2, nodeRange.end) : null;
+			}
+		}
+		return null;
+	}
 	const childEnd = Array.isArray(node.children)
 		? Math.max(nodeRange.start, ...node.children.map((child) => child.position?.end.offset ?? nodeRange.start))
 		: nodeRange.start;
@@ -66,7 +85,7 @@ const getInlineLinkTargetRange = (source, node) => {
 	return scanDestination(source, delimiter + 2, nodeRange.end);
 };
 
-const getDefinitionTargetRange = (source, node) => {
+export const getDefinitionTargetRange = (source, node) => {
 	const nodeRange = getNodeRange(node);
 	if (!nodeRange) return null;
 	const delimiter = source.indexOf(']:', nodeRange.start);
@@ -82,16 +101,16 @@ export const extractMarkdownLinks = ({ source, tree, lineOffset = 0 }) => {
 	const definitions = new Map();
 	visitNodes(tree, (node) => {
 		if (node.type !== 'definition') return;
-		definitions.set(node.identifier, node);
+		if (!definitions.has(node.identifier)) definitions.set(node.identifier, node);
 	});
 
 	const links = [];
 	visitNodes(tree, (node) => {
-		if (node.type === 'link') {
+		if (node.type === 'link' || node.type === 'image' && /^(?:\/|https?:)/i.test(node.url ?? '')) {
 			const range = getNodeRange(node);
 			const targetRange = getInlineLinkTargetRange(source, node);
 			links.push({
-				kind: 'markdown-link',
+				kind: node.type === 'image' ? 'markdown-image-link' : 'markdown-link',
 				column: node.position?.start.column ?? 1,
 				line: lineOffset + (node.position?.start.line ?? 1),
 				range,
@@ -102,14 +121,15 @@ export const extractMarkdownLinks = ({ source, tree, lineOffset = 0 }) => {
 			return;
 		}
 
-		if (node.type !== 'linkReference') return;
+		if (!['linkReference', 'imageReference'].includes(node.type)) return;
 		const definition = definitions.get(node.identifier);
-		if (!definition) return;
+		if (!definition || node.type === 'imageReference' && !/^(?:\/|https?:)/i.test(definition.url ?? '')) return;
 		const targetRange = getDefinitionTargetRange(source, definition);
 		links.push({
 			kind: 'markdown-reference-link',
 			column: node.position?.start.column ?? 1,
 			definitionLine: lineOffset + (definition.position?.start.line ?? 1),
+			definitionSource: source.slice(definition.position.start.offset, definition.position.end.offset),
 			line: lineOffset + (node.position?.start.line ?? 1),
 			range: getNodeRange(node),
 			target: definition.url ?? '',

package/scripts/lib/navigation-model.mjs

@@ -17,24 +17,11 @@ const getListedNodes = (nodes) => nodes.filter((node) => node.isHome || node.lis
 
 const getNodeDepth = (node) => node.depth ?? 1;
 
-const getTopLevelPagePath = (pagePath) => pagePath?.split('/')[0] ?? '';
-
-const getActiveBranchNodes = (nodes, currentPage) => {
-	if (!currentPage) return [];
-	if (currentPage.isHome) return nodes.filter((node) => node.isHome);
-
-	const rootPath = getTopLevelPagePath(currentPage.pagePath);
-	return nodes.filter((node) => (
-		node.pagePath === rootPath
-		|| node.pagePath?.startsWith(`${rootPath}/`)
-	));
-};
-
 export const getAutomaticNavigationMode = (nodes) => {
 	const listedNodes = getListedNodes(nodes);
 	if (listedNodes.length <= 1) return 'sections';
 
-	return listedNodes.some((node) => node.kind === 'category' || getNodeDepth(node) > 1)
+	return listedNodes.some((node) => getNodeDepth(node) > 1)
 		? 'tree'
 		: 'top';
 };
@@ -42,10 +29,6 @@ export const getAutomaticNavigationMode = (nodes) => {
 export const resolveNavigationModel = ({ mode = 'automatic', nodes }) => {
 	const requestedMode = assertNavigationMode(mode);
 	const listedNodes = getListedNodes(nodes);
-	const hasCategories = listedNodes.some((node) => node.kind === 'category');
-	if (hasCategories && requestedMode !== 'automatic' && requestedMode !== 'tree') {
-		throw new Error(`Navigation categories require tree navigation. Remove navigation.mode: ${requestedMode}, or set navigation.mode: tree.`);
-	}
 	const maximumDepth = listedNodes.reduce((maximum, node) => (
 		Math.max(maximum, getNodeDepth(node))
 	), 1);
@@ -57,33 +40,8 @@ export const resolveNavigationModel = ({ mode = 'automatic', nodes }) => {
 			: requestedMode,
 		requestedMode,
 		listedNodeCount: listedNodes.length,
-		hasCategories,
+		hasCategories: false,
 		hasNestedPages,
 		maximumDepth,
 	});
 };
-
-export const resolvePageContentsPlacement = ({
-	navigationMode,
-	nodes,
-	currentPage,
-	headingCount,
-}) => {
-	const listedNodes = getListedNodes(nodes);
-	const activeBranchNodes = getActiveBranchNodes(listedNodes, currentPage);
-	const activeBranchDepth = activeBranchNodes.reduce((maximum, node) => (
-		Math.max(maximum, getNodeDepth(node))
-	), 0);
-	const hasPageContents = headingCount >= 2;
-	const placement = currentPage?.isHome || navigationMode !== 'tree' || !hasPageContents
-		? 'none'
-		: activeBranchDepth <= 2
-			? 'page-tree'
-			: 'contents-rail';
-
-	return Object.freeze({
-		activeBranchDepth,
-		hasPageContents,
-		placement,
-	});
-};

package/scripts/lib/navigation-review.mjs

@@ -26,12 +26,11 @@ const getTreeMetrics = (root) => {
 	const nodes = flattenSiteNavigationTree([root]);
 	const rootDepth = root.node.depth;
 	return {
-		categoryCount: nodes.filter(({ node }) => node.kind === 'category').length,
 		maximumLevels: nodes.reduce((maximum, { node }) => (
 			Math.max(maximum, node.depth - rootDepth + 1)
 		), 1),
 		nodeCount: nodes.length,
-		pageCount: nodes.filter(({ node }) => node.kind === 'page').length,
+		pageCount: nodes.length,
 	};
 };
 
@@ -58,7 +57,7 @@ const getSiblingGroups = (roots) => {
 	return groups;
 };
 
-const toGraphError = (diagnostic) => ({
+const toGraphFinding = (diagnostic) => ({
 	code: diagnostic.code,
 	...(diagnostic.fix ? { fix: diagnostic.fix } : {}),
 	...(diagnostic.reference?.line ? { line: diagnostic.reference.line } : {}),
@@ -85,10 +84,8 @@ const getNavigationEntries = (siteStructure, linkGraph) => {
 	]));
 
 	return siteStructure.nodes.map((siteNode) => {
-		const page = siteNode.kind === 'page'
-			? pagesByDirectory.get(siteNode.pageDirectory)
-			: null;
-		if (siteNode.kind === 'page' && !page) {
+		const page = pagesByDirectory.get(siteNode.pageDirectory);
+		if (!page) {
 			throw new Error(`Navigation review could not find parsed content for ${siteNode.contentLabel}.`);
 		}
 
@@ -99,8 +96,8 @@ const getNavigationEntries = (siteStructure, linkGraph) => {
 				navigation: {
 					listed: siteNode.isHome || (page?.navigation.listed ?? true),
 				},
-				pathname: siteNode.kind === 'page' ? page.pathname : null,
-				title: siteNode.kind === 'page' ? page.title : siteNode.label,
+				pathname: page.pathname,
+				title: page.title,
 			},
 			page,
 			sections: [],
@@ -121,7 +118,7 @@ const getNavigationModes = ({ entries, listedEntries, requestedNavigationMode })
 	const modes = new Map();
 	const seenErrors = new Set();
 
-	for (const entry of entries.filter(({ node }) => node.kind === 'page')) {
+	for (const entry of entries) {
 		try {
 			const model = resolveNavigationModel({
 				currentPage: {
@@ -173,9 +170,7 @@ export const createNavigationReview = ({
 		requestedNavigationMode,
 	});
 
-	const pages = completeEntries
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ headings, node, page }) => {
+	const pages = completeEntries.map(({ headings, node, page }) => {
 			const incomingPageLinkCount = resolvedPageReferences.filter(({ resolution }) => (
 				resolution.page.pathname === page.pathname
 			)).length;
@@ -200,21 +195,6 @@ export const createNavigationReview = ({
 			};
 		});
 
-	const categories = completeEntries
-		.filter(({ node }) => node.kind === 'category')
-		.map(({ children, node }) => ({
-			childCount: children.length,
-			depth: node.depth,
-			listed: listedPaths.has(node.pagePath),
-			listedChildCount: listedPaths.has(node.pagePath)
-				? (listedEntries.find(({ node: listedNode }) => listedNode.pagePath === node.pagePath)?.children.length ?? 0)
-				: 0,
-			parentPath: node.parentPagePath === null ? null : `/${node.parentPagePath}/`,
-			path: logicalPathname(node),
-			source: node.categorySourceLabel,
-			title: node.title,
-		}));
-
 	const branches = listedTree.map((root) => {
 		const metrics = getTreeMetrics(root);
 		const branchPaths = new Set(flattenSiteNavigationTree([root]).map(({ node }) => node.pagePath));
@@ -235,7 +215,8 @@ export const createNavigationReview = ({
 	const siblingGroups = getSiblingGroups(listedTree);
 	const widestSiblingCount = siblingGroups.reduce((maximum, group) => Math.max(maximum, group.count), 0);
 	const observations = [
-		...siteStructure.warnings.map(toStructureObservation),
+		...siteStructure.warnings.filter(({ code }) => code !== 'empty-category').map(toStructureObservation),
+		...linkGraph.diagnostics.filter(({ severity }) => severity === 'warning').map(toGraphFinding),
 	];
 	const unlistedPages = pages.filter(({ listed }) => !listed);
 	if (unlistedPages.length > 0) {
@@ -246,13 +227,6 @@ export const createNavigationReview = ({
 	}
 
 	const recommendations = [];
-	for (const category of categories.filter(({ listed, listedChildCount }) => listed && listedChildCount === 1)) {
-		recommendations.push({
-			code: 'single-child-category',
-			message: `${category.title} (${category.path}) has one listed child. Keep the category when its label adds useful orientation; otherwise consider moving the child to the category's parent.`,
-			path: category.path,
-		});
-	}
 	for (const branch of branches.filter(({ maximumLevels }) => maximumLevels >= thresholds.deepBranchLevels)) {
 		recommendations.push({
 			code: 'deep-branch',
@@ -279,7 +253,7 @@ export const createNavigationReview = ({
 
 	return {
 		command: 'navigation:review',
-		schemaVersion: 1,
+		schemaVersion: 2,
 		thresholds: {
 			deepBranchLevels: thresholds.deepBranchLevels,
 			sectionCount: thresholds.sectionCount,
@@ -287,10 +261,8 @@ export const createNavigationReview = ({
 		},
 		site: {
 			branchCount: branches.length,
-			categoryCount: categories.length,
 			effectiveNavigationModes,
 			internalReferenceCount: linkGraph.references.length,
-			listedCategoryCount: categories.filter(({ listed }) => listed).length,
 			listedPageCount: pages.filter(({ listed }) => listed).length,
 			maximumDepth: listedEntries.reduce((maximum, { node }) => Math.max(maximum, node.depth), 0),
 			pageCount: pages.length,
@@ -301,9 +273,8 @@ export const createNavigationReview = ({
 		branches,
 		siblingGroups,
 		pages,
-		categories,
 		errors: [
-			...linkGraph.diagnostics.map(toGraphError),
+			...linkGraph.diagnostics.filter(({ severity }) => severity === 'error').map(toGraphFinding),
 			...navigationErrors,
 		],
 		observations,
@@ -330,13 +301,13 @@ export const formatNavigationReviewText = (review) => {
 		'',
 		'Site',
 		`- Navigation: ${review.site.requestedNavigationMode} configured; ${review.site.effectiveNavigationModes.join(', ') || 'unresolved'} effective`,
-		`- Content: ${plural(review.site.pageCount, 'page')} (${review.site.listedPageCount} listed), ${plural(review.site.categoryCount, 'category', 'categories')} (${review.site.listedCategoryCount} listed)`,
+		`- Content: ${plural(review.site.pageCount, 'page')} (${review.site.listedPageCount} listed)`,
 		`- Structure: ${plural(review.site.branchCount, 'top-level branch', 'top-level branches')}, ${review.site.maximumDepth} listed ${review.site.maximumDepth === 1 ? 'level' : 'levels'}, widest sibling group ${review.site.widestSiblingCount}`,
 		`- Links: ${plural(review.site.internalReferenceCount, 'internal reference')}, ${review.site.resolvedPageLinkCount} resolved to pages`,
 		'',
 		'Branches',
 		...review.branches.map((branch) => (
-			`- ${branch.title} (${branch.path}; ${branch.kind}): ${plural(branch.pageCount, 'page')}, ${plural(branch.categoryCount, 'category', 'categories')}, ${plural(branch.maximumLevels, 'visible level')}; navigation ${branch.navigationModes.join(', ') || 'unresolved'}`
+			`- ${branch.title} (${branch.path}; ${branch.kind}): ${plural(branch.pageCount, 'page')}, ${plural(branch.maximumLevels, 'visible level')}; navigation ${branch.navigationModes.join(', ') || 'unresolved'}`
 		)),
 		'',
 		'Pages',
@@ -344,13 +315,6 @@ export const formatNavigationReviewText = (review) => {
 			`- ${page.title} (${page.pathname}; ${page.listed ? 'listed' : 'not listed'}): H2 ${page.h2Count}, H3 ${page.h3Count}; page links ${page.outgoingPageLinkCount} out / ${page.incomingPageLinkCount} in; navigation ${page.navigationMode ?? 'unresolved'}`
 		)),
 		'',
-		'Categories',
-		...(review.categories.length === 0
-			? ['- None.']
-			: review.categories.map((category) => (
-				`- ${category.title} (${category.path}; ${category.listed ? 'listed' : 'not listed'}): ${category.listedChildCount} listed of ${plural(category.childCount, 'direct child', 'direct children')}`
-			))),
-		'',
 		...formatFindingSection('Errors', review.errors),
 		'',
 		...formatFindingSection('Observations', review.observations),

package/scripts/lib/norna-markdown-blocks.mjs

@@ -56,7 +56,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 					xl: value('Extra large', 'Use the largest card and image size.'),
 				}),
 			}),
-			width: field('Override the root theme\'s maximum width for this card list.', {
+			width: field('Override the shared theme\'s maximum width for this card list.', {
 				values: Object.freeze({
 					text: value('Text', 'Match the active body-text width, including a reader-selected reading width.'),
 					narrow: value('Narrow', 'Limit the complete card list to at most 48rem.'),
@@ -534,63 +534,6 @@ export const splitNornaRenderedBlocks = (html, blocks) => {
 	return result.filter((block) => block.type !== 'html' || block.html.trim());
 };
 
-const maskFencedCodeBlocks = (markdown) => {
-	const lines = normalizeLines(markdown);
-	const maskedLines = [];
-	let index = 0;
-
-	while (index < lines.length) {
-		const fence = getFenceInfo(lines[index]);
-		if (!fence || fence.length < 3) {
-			maskedLines.push(lines[index]);
-			index += 1;
-			continue;
-		}
-
-		let closingIndex = -1;
-		for (let candidateIndex = index + 1; candidateIndex < lines.length; candidateIndex += 1) {
-			if (getFenceCloseInfo(lines[candidateIndex], fence)) {
-				closingIndex = candidateIndex;
-				break;
-			}
-		}
-
-		if (closingIndex === -1) {
-			maskedLines.push(lines[index]);
-			index += 1;
-			continue;
-		}
-
-		for (let maskedIndex = index; maskedIndex <= closingIndex; maskedIndex += 1) {
-			maskedLines.push(lines[maskedIndex].replace(/[^\r\n]/g, ' '));
-		}
-		index = closingIndex + 1;
-	}
-
-	return maskedLines.join('\n');
-};
-
-const isExternalImageTarget = (target) => /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//');
-const isRootRelativePublicTarget = (target) => target.startsWith('/');
-
-export const extractMarkdownImageReferences = (markdown) => {
-	const masked = maskFencedCodeBlocks(markdown);
-	const references = [];
-	const imageRegex = /!\[[^\]\n]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
-
-	for (const match of masked.matchAll(imageRegex)) {
-		const target = match[1] ?? '';
-		if (!target || target.startsWith('#') || isExternalImageTarget(target) || isRootRelativePublicTarget(target)) continue;
-
-		references.push({
-			target,
-			line: getLineNumber(markdown, match.index ?? 0),
-		});
-	}
-
-	return references;
-};
-
 export const getNornaBlockImageReferences = (blocks) =>
 	blocks.flatMap((block) => {
 		if (block.type === 'card-list') {

package/scripts/lib/norna-markdown-render-plugin.mjs

@@ -3,6 +3,26 @@ import { nornaBlockTypes } from './norna-markdown-blocks.mjs';
 import projectConfig from './project-config.mjs';
 import { getSemanticCalloutMarker } from './semantic-callouts.mjs';
 import { applyTableRowHeaderDeclaration } from './table-row-headers.mjs';
+import { classifyMarkdownImage, getImageDefinitions } from './markdown-images.mjs';
+
+const escapeAttribute = (value) => String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const markManagedImage = (node, context) => {
+	let root = node;
+	while (context.parent(root)) root = context.parent(root);
+	const destination = node.type === 'image' ? node : getImageDefinitions(root).get(node.identifier);
+	if (!destination) return;
+	const result = classifyMarkdownImage(destination.url ?? '');
+	if (result.kind === 'external') return;
+	if (result.kind === 'invalid') throw new Error(`Local Markdown image "${destination.url}" must reference a .jpg, .jpeg, .png or .svg file directly in this page's images/ folder.`);
+	const title = destination.title == null ? '' : ` title="${escapeAttribute(destination.title)}"`;
+	// Raw HTML keeps Astro's independent image importer from processing these
+	// sources. The page renderer resolves this marker through Norna's manifest.
+	context.replaceNode(node, { type: 'html', value: `<img data-norna-managed-image="${escapeAttribute(result.image)}" alt="${escapeAttribute(node.alt ?? '')}"${title}>` });
+};
+
+export const nornaMarkdownImagePlugin = defineMdastPlugin({
+	name: 'norna-markdown-images', image: markManagedImage, imageReference: markManagedImage,
+});
 
 const stateKey = 'nornaMarkdownRender';
 
@@ -33,6 +53,8 @@ const hasBlockquoteAncestor = (node, context) => {
 
 export const nornaMarkdownRenderPlugin = defineMdastPlugin({
 	name: 'norna-markdown-render',
+	image: markManagedImage,
+	imageReference: markManagedImage,
 	blockquote(node, context) {
 		const marker = getSemanticCalloutMarker(node);
 		if (
@@ -88,6 +110,13 @@ export const nornaMarkdownRenderPlugin = defineMdastPlugin({
 		});
 	},
 	heading(node, context) {
+		if (node.depth === 3) {
+			if (context.parent(node)?.type !== 'root') return;
+			context.setProperty(node, 'data', {
+				hProperties: { 'data-norna-page-heading': 'true' },
+			});
+			return;
+		}
 		if (node.depth !== 1 && node.depth !== 2) return;
 		const state = getState(context);
 		const regionIndex = state.regionIndex;

package/scripts/lib/page-aliases.mjs

@@ -2,6 +2,11 @@ import { getSiteNodePathname } from './site-page-urls.mjs';
 import { sitemapFilename } from './sitemap.mjs';
 
 export const getGeneratedSiteRoutes = ({ searchEnabled = false } = {}) => Object.freeze([
+	Object.freeze({
+		kind: 'generated-route',
+		label: 'Norna generated 404 page',
+		pathname: '/404.html',
+	}),
 	Object.freeze({
 		kind: 'generated-route',
 		label: `Norna generated ${sitemapFilename}`,
@@ -154,7 +159,9 @@ export const createPageAliasModel = ({
 					contentFile,
 					fix: conflict.kind === 'page-alias'
 						? 'Keep the old URL on exactly one current page.'
-						: 'Remove or change the alias. A public URL can identify only one site resource.',
+						: conflict.kind === 'page'
+							? `Rename the page at ${conflict.label}, or remove ${pathname} from the previous addresses in ${contentLabel}. Removing it may break old links.`
+							: 'Remove or change the alias. A public URL can identify only one site resource.',
 					message: `Page alias "${pathname}" in ${contentLabel} conflicts with ${describeIdentity(conflict)}.`,
 					severity: 'error',
 				});