@janga/norna 0.7.28 → 0.7.30

package/scripts/move-site-page.mjs

@@ -1,135 +1,48 @@
-import { applyPageMovePlan } from './lib/page-move-apply.mjs';
 import path from 'node:path';
-import {
-	createPageMovePlan,
-	formatPageMovePlan,
-} from './lib/page-move-plan.mjs';
-import {
-	getSiteLinkGraph,
-	getSitePublicFiles,
-} from './lib/site-link-graph.mjs';
-import {
-	sitePagesDir,
-	sitePagesLabel,
-	siteProjectRoot,
-	siteDir,
-} from './lib/site-paths.mjs';
-import { getSiteStructure } from './lib/site-structure.mjs';
-
-const usage = `
-Usage:
-  norna page:move <old-url> <new-url> [--order <NNN>] [--no-aliases] [--write]
-
-Examples:
-  norna page:move /guides/install/ /guides/installation/
-  norna page:move /guides/install/ /reference/install/ --write
-
-The command is a dry run unless --write is present. If the old page has
-already been moved by hand, the same command reconciles its links and aliases.
-`.trim();
-
-const parseOrder = (value) => {
-	if (!/^\d{1,3}$/.test(value ?? '')) {
-		throw new Error(`Invalid --order "${value ?? ''}". Use an integer from 1 to 999.\n${usage}`);
-	}
-	const order = Number.parseInt(value, 10);
-	if (order < 1 || order > 999) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.\n${usage}`);
-	}
-	return order;
-};
-
-const parseArgs = (rawArgs) => {
-	const options = {
-		help: false,
-		order: null,
-		preserveAliases: true,
-		urls: [],
-		write: false,
-	};
-	const seen = new Set();
-
-	for (let index = 0; index < rawArgs.length; index += 1) {
-		const arg = rawArgs[index];
-		if (arg === '-h' || arg === '--help') {
-			options.help = true;
-			continue;
-		}
-		if (arg === '--write') {
-			if (seen.has('write')) throw new Error(`--write may be specified only once.\n${usage}`);
-			seen.add('write');
-			options.write = true;
-			continue;
-		}
-		if (arg === '--no-aliases') {
-			if (seen.has('aliases')) throw new Error(`--no-aliases may be specified only once.\n${usage}`);
-			seen.add('aliases');
-			options.preserveAliases = false;
-			continue;
-		}
-		if (arg === '--order' || arg.startsWith('--order=')) {
-			if (seen.has('order')) throw new Error(`--order may be specified only once.\n${usage}`);
-			seen.add('order');
-			const inlineValue = arg.startsWith('--order=') ? arg.slice('--order='.length) : null;
-			const value = inlineValue ?? rawArgs[index + 1];
-			if (inlineValue === null) index += 1;
-			options.order = parseOrder(value);
-			continue;
-		}
-		if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}\n${usage}`);
-		options.urls.push(arg);
-	}
-
-	if (!options.help && options.urls.length !== 2) {
-		throw new Error(`page:move requires an old URL and a new URL.\n${usage}`);
-	}
-	return options;
-};
-
-const toDisplayPath = (filePath) => {
-	const relativePath = path.relative(siteProjectRoot, filePath);
-	return (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
-		? relativePath
-		: filePath).split(path.sep).join('/');
-};
-
-const main = async () => {
-	const options = parseArgs(process.argv.slice(2));
-	if (options.help) {
-		console.log(usage);
-		return;
-	}
-
-	const siteStructure = await getSiteStructure();
-	const [graph, publicFiles] = await Promise.all([
-		getSiteLinkGraph({ siteStructure }),
-		getSitePublicFiles(),
-	]);
-	const plan = await createPageMovePlan({
-		from: options.urls[0],
-		graph,
-		order: options.order,
-		preserveAliases: options.preserveAliases,
-		publicFiles,
-		sitePagesDir,
-		sitePagesLabel,
-		siteStructure,
-		to: options.urls[1],
-	});
-
-	console.log(formatPageMovePlan(plan, toDisplayPath).join('\n'));
-	if (!options.write) {
-		console.log('\nDry run only. Run the same command with --write to apply this plan.');
-		return;
-	}
-
-	await applyPageMovePlan(plan, { siteRoot: siteDir });
-	console.log(`\nPage move completed: ${plan.from} -> ${plan.to}`);
-};
-
+import { applyPageMovePlan } from './lib/page-move-apply.mjs';
+import { createPageMovePlan, formatPageMovePlan } from './lib/page-move-plan.mjs';
+import { planEditorPagePlacement, applyEditorPagePlacement } from './lib/editor-page-placement.mjs';
+import { parsePlacementArguments, confirmCliRenumbering, describeRenumbering } from './lib/page-placement-cli.mjs';
+import { readEditorLinkState } from './lib/editor-site-links.mjs';
+import { sitePagesDir, sitePagesLabel, siteProjectRoot, siteDir } from './lib/site-paths.mjs';
+
+const usage = `Usage:
+  norna page:move <old-url> <new-url> [--order <integer>]
+  norna page:move <page-url> --before <target-url> | --after <target-url>
+  norna page:move <page-url> --parent <parent-url> [--first | --last]
+
+Options: --no-aliases, --write, --dry-run, --allow-renumber
+Dry run unless --write is present. The URL-to-URL form also reconciles a page
+already moved by hand. Renumbering other pages requires confirmation.`;
+const display = filename => path.relative(siteProjectRoot, filename) || filename;
 try {
-	await main();
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
-}
+ const options = parsePlacementArguments(process.argv.slice(2));
+ if (options.help) { console.log(usage); process.exit(0); }
+ if (options.slug !== null) throw new Error('Use the new URL to change a slug with page:move.');
+ const relative = options.placement !== null;
+ if (options.positionals.length !== (relative ? 1 : 2)) throw new Error(usage);
+ if (relative && options.order !== null) throw new Error('Do not combine --order with a placement selector.');
+ const state = await readEditorLinkState({ siteRoot: siteDir });
+ if (state.incomplete.length) throw new Error(state.incomplete.join('\n'));
+ let plan;
+ if (relative) {
+  const find = url => state.structure.nodes.find(node => (node.isHome ? '/' : `/${node.pagePath}/`) === url);
+  const source = find(options.positionals[0]), target = find(options.target);
+  if (!source || !target) throw new Error('Choose existing source and target page URLs.');
+  plan = await planEditorPagePlacement({ siteRoot: siteDir, sourcePath: source.contentPath, targetPath: target.contentPath,
+   placement: options.placement, preserveAliases: options.preserveAliases });
+  console.log(`Page placement: ${plan.sourceUrl} ${options.placement} ${options.target}\nOrder: ${plan.sourceOrder}`);
+  if (plan.movePreview) console.log(formatPageMovePlan(plan.movePreview, display).join('\n'));
+  else if (plan.orderChanges.length) console.log(describeRenumbering(plan.orderChanges, display));
+ } else {
+  plan = await createPageMovePlan({ from: options.positionals[0], to: options.positionals[1], order: options.order,
+   preserveAliases: options.preserveAliases, graph: state.graph, publicFiles: state.publicFiles,
+   siteStructure: state.structure, sitePagesDir, sitePagesLabel, generatedRoutes: state.generatedRoutes });
+  console.log(formatPageMovePlan(plan, display).join('\n'));
+ }
+ if (!options.write) { console.log('\nDry run only. Run with --write to apply this plan.'); process.exit(0); }
+ if (!await confirmCliRenumbering(plan.orderChanges, options)) { console.log('Cancelled. No files changed.'); process.exit(0); }
+ if (relative) await applyEditorPagePlacement(plan, { allowRenumber: true });
+ else await applyPageMovePlan(plan, { siteRoot: siteDir, generatedRoutes: state.generatedRoutes, allowRenumber: true });
+ console.log(`Page move completed: ${plan.sourceUrl ?? plan.from} -> ${plan.destinationUrl ?? plan.to}. ${plan.orderChanges.length} existing sibling page(s) renumbered.`);
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/scripts/sync-content-sections.mjs

@@ -1,3 +1,4 @@
+import { getSiteAttachments } from './lib/page-attachments.mjs';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import path from 'node:path';
@@ -272,7 +273,7 @@ for (const contentFile of contentFiles) {
 		prelude,
 		regions: sections,
 	} = page;
-	for (const issue of page.diagnostics.filter((candidate) => candidate.code === 'heading-inside-details')) {
+	for (const issue of page.diagnostics.filter((candidate) => ['heading-inside-details', 'invalid-markdown-image'].includes(candidate.code))) {
 		addContentIssue(contentFile, issue);
 	}
 	for (const issue of page.noteDiagnostics) {
@@ -468,12 +469,17 @@ for (const context of contentFileContexts) {
 }
 
 const siteLinkGraph = createSiteLinkGraph({
+	siteUrl: projectConfig.site.url,
+	attachments: await getSiteAttachments(siteStructure),
 	pageDocuments: contentFileContexts.map(({ contentFile, frontmatterData, page }) => ({
 		contentFile,
 		data: frontmatterData,
 		document: page,
 	})),
-	publicFiles: await getSitePublicFiles(),
+	publicFiles: await getSitePublicFiles(undefined, projectConfig).catch(error => {
+		addIssue({ severity: 'error', message: error.message, fix: 'Use the supported public-file locations and verificationFiles settings.' });
+		return [];
+	}),
 	siteStructure,
 	generatedRoutes: getGeneratedSiteRoutes({ searchEnabled: projectConfig.search.enabled }),
 });
@@ -531,14 +537,6 @@ for (const context of contentFileContexts) {
 	for (const section of sections) {
 		if (!validSections.has(section)) continue;
 
-		for (const reference of section.markdownImages) {
-			addSectionIssue(contentFile, section, {
-				severity: 'warning',
-				message: `Markdown image "${reference.target}" references a local image that is not managed by Norna.`,
-				fix: 'Use an image-stack, image-carousel, or card-list block for site images that should be validated, processed and synced.',
-			});
-		}
-
 		const { blocks, errors: blockErrors } = blockResultsBySection.get(section) ?? { blocks: [], errors: [] };
 		for (const error of blockErrors) {
 			addSectionIssue(contentFile, section, {

package/scripts/sync-site-public.mjs

@@ -5,84 +5,62 @@ import { createSitemapXml, sitemapFilename } from './lib/sitemap.mjs';
 import {
 	astroPublicDir,
 	astroPublicLabel,
-	sitePublicDir,
 	sitePublicLabel,
 } from './lib/site-paths.mjs';
 import { getSiteStructure } from './lib/site-structure.mjs';
 import { getSiteLinkGraph } from './lib/site-link-graph.mjs';
 import { assertCategoryDestinationModel } from './lib/category-destinations.mjs';
 
-const keepAstroPublicEntries = new Set([
-	'images',
-	...(projectConfig.search.enabled ? ['pagefind'] : []),
-]);
+const main = async () => {
+	const readDirectory = async (directory) => {
+		try {
+			return await readdir(directory, { withFileTypes: true });
+		} catch (error) {
+			if (error?.code === 'ENOENT') {
+				return [];
+			}
 
-const readDirectory = async (directory) => {
-	try {
-		return await readdir(directory, { withFileTypes: true });
-	} catch (error) {
-		if (error?.code === 'ENOENT') {
-			return [];
+			throw error;
 		}
+	};
 
-		throw error;
-	}
-};
-
-const sourceEntries = await readDirectory(sitePublicDir);
-const generatedPublicFiles = [
-	{
-		filename: sitemapFilename,
-		explanation: `Norna generates ${sitemapFilename} from the public page tree and the URL in site/site-config/settings.yaml.`,
-	},
-	{
-		filename: '404.html',
-		explanation: 'Norna generates 404.html as the site\'s localized missing-page response.',
-	},
-	...(projectConfig.search.enabled ? [{
-		filename: 'pagefind',
-		explanation: 'Norna generates pagefind/ from the rendered editorial content when search is enabled.',
-	}] : []),
-];
-for (const generatedFile of generatedPublicFiles) {
-	const conflict = sourceEntries.find(({ name }) => name.toLowerCase() === generatedFile.filename);
-	if (!conflict) continue;
-
-	throw new Error([
-		`${sitePublicLabel}/${conflict.name} conflicts with Norna's generated ${generatedFile.filename}.`,
-		`Remove that source file. ${generatedFile.explanation}`,
-	].join('\n'));
-}
-
-const siteStructure = await getSiteStructure();
-const { categoryModel } = await getSiteLinkGraph({ siteStructure });
-const { destinations: categoryDestinations } = assertCategoryDestinationModel(categoryModel);
-const sitemapXml = createSitemapXml({
-	siteStructure,
-	siteUrl: projectConfig.site.url,
-	categoryDestinations,
-});
+	const siteStructure = await getSiteStructure();
+	const { categoryModel, attachments, diagnostics, publicFilesByPathname } = await getSiteLinkGraph({ siteStructure });
+	const outputErrors = diagnostics.filter(issue => !issue.reference && issue.severity === 'error');
+	if (outputErrors.length) throw new Error(outputErrors.map(issue => issue.message).join('\n'));
+	const { destinations: categoryDestinations } = assertCategoryDestinationModel(categoryModel);
+	const sitemapXml = createSitemapXml({
+		siteStructure,
+		siteUrl: projectConfig.site.url,
+		categoryDestinations,
+	});
 
-await mkdir(astroPublicDir, { recursive: true });
+	await mkdir(astroPublicDir, { recursive: true });
 
-for (const entry of await readDirectory(astroPublicDir)) {
-	if (keepAstroPublicEntries.has(entry.name)) {
-		continue;
+	for (const entry of await readDirectory(astroPublicDir)) {
+		if (entry.name !== '_norna') await rm(path.join(astroPublicDir, entry.name), { force: true, recursive: true });
+	}
+	const resources = path.join(astroPublicDir, '_norna');
+	for (const entry of await readDirectory(resources)) {
+		if (entry.name === 'images' || entry.name === 'search' && projectConfig.search.enabled) continue;
+		await rm(path.join(resources, entry.name), { force: true, recursive: true });
+	}
+	for (const file of new Set(publicFilesByPathname.values())) {
+		const destination = path.join(astroPublicDir, file.pathname.slice(1));
+		await mkdir(path.dirname(destination), { recursive: true });
+		await cp(file.filePath, destination, { force: false, errorOnExist: true });
 	}
 
-	await rm(path.join(astroPublicDir, entry.name), { force: true, recursive: true });
-}
-
-for (const entry of sourceEntries) {
-	await cp(
-		path.join(sitePublicDir, entry.name),
-		path.join(astroPublicDir, entry.name),
-		{ force: true, recursive: true },
-	);
-}
+	for (const file of attachments.files) {
+		const destination = path.join(astroPublicDir, file.pathname.slice(1));
+		await mkdir(path.dirname(destination), { recursive: true });
+		await cp(file.filePath, destination, { force: false, errorOnExist: true });
+	}
+	await writeFile(path.join(astroPublicDir, sitemapFilename), sitemapXml);
 
-await writeFile(path.join(astroPublicDir, sitemapFilename), sitemapXml);
+	console.log(`Synced ${sitePublicLabel}/ to ${astroPublicLabel}/.`);
+	const pageCount = siteStructure.contentFiles.length + categoryDestinations.filter(({ kind }) => kind === 'listing').length;
+	console.log(`Generated ${astroPublicLabel}/${sitemapFilename} for ${pageCount} public page${pageCount === 1 ? '' : 's'}.`);
+};
 
-console.log(`Synced ${sitePublicLabel}/ to ${astroPublicLabel}/.`);
-const pageCount = siteStructure.contentFiles.length + categoryDestinations.filter(({ kind }) => kind === 'listing').length;
-console.log(`Generated ${astroPublicLabel}/${sitemapFilename} for ${pageCount} public page${pageCount === 1 ? '' : 's'}.`);
+await main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/src/components/ContentBlocks.astro

@@ -4,6 +4,7 @@ import ImageCarousel from './ImageCarousel.astro';
 import ImageStack from './ImageStack.astro';
 import PageList from './PageList.astro';
 import type { SectionContentBlock } from '../lib/sectionContent';
+import { renderNestedMarkdownImages } from '../lib/markdownImages';
 
 interface Props {
 	blocks: SectionContentBlock[];
@@ -20,7 +21,7 @@ const firstMediaIndex = blocks.findIndex((block) => block.type === 'image-stack'
 ---
 
 {blocks.map((block, index) => {
-	if (block.type === 'html') return <div class="section-markdown" set:html={block.html} />;
+	if (block.type === 'html') return <div class="section-markdown" set:html={renderNestedMarkdownImages(block.html, title, images.maxAvailableWidthPercent)} />;
 	if (block.type === 'tabs') return (
 		<div class="content-tabs content-block-note-lane-boundary" data-content-tabs>
 			<div class="content-tabs-controls" data-tabs-controls hidden></div>

package/src/components/ImageStack.astro

@@ -43,10 +43,11 @@ const managedImageSizes = getManagedImageSizes(maxAvailableWidthPercent);
 				<div class="managed-image-frame">
 					<a
 						class="managed-image-inspection-link"
-						href={inspection.href}
-						aria-label={inspectionLabel}
+						href={image.href ?? inspection.href}
+						title={image.linkTitle}
+						aria-label={image.href === undefined ? inspectionLabel : undefined}
 						aria-describedby={captionId}
-						data-image-inspection-trigger
+						data-image-inspection-trigger={image.href === undefined ? '' : undefined}
 						data-image-intrinsic-width={inspection.width}
 						data-image-intrinsic-height={inspection.height}
 						data-image-inspection-scalable={inspection.scalable ? 'true' : undefined}
@@ -56,12 +57,13 @@ const managedImageSizes = getManagedImageSizes(maxAvailableWidthPercent);
 							{...getImageAttributes(image.src ?? image.image, managedImageSizes)}
 							class:list={['managed-image', getImageClass(image)]}
 							alt={image.alt ?? ''}
+							title={image.title}
 							aria-describedby={captionId}
 							{...getImageLoadingProps(isPriorityItem)}
 						/>
-						<span class="managed-image-inspection-affordance" aria-hidden="true">
+						{image.href === undefined && <span class="managed-image-inspection-affordance" aria-hidden="true">
 							<Maximize2 size={18} stroke-width={2} />
-						</span>
+						</span>}
 					</a>
 				</div>
 				{image.caption && (

package/src/components/SearchPage.astro

@@ -1,4 +1,5 @@
 ---
+import { searchOutputDirectory } from '../../scripts/lib/publication-paths.mjs';
 import { getCollection } from 'astro:content';
 import { ArrowLeft } from '@lucide/astro';
 import { resolveNavigationModel } from '../../scripts/lib/navigation-model.mjs';
@@ -84,7 +85,7 @@ const hasNavigationRailFrame = navigationModel.requestedMode === 'tree'
 		navigationModel.requestedMode === 'automatic'
 		&& (navigationModel.hasNestedPages || navigationModel.hasCategories)
 	);
-const bundlePath = withBasePath(projectConfig.site.basePath, '/pagefind/');
+const bundlePath = withBasePath(projectConfig.site.basePath, `/${searchOutputDirectory}/`);
 const pagefindTranslationOption = projectConfig.locale.pagefindTranslations
 	? `,\n\t\t\ttranslations: ${JSON.stringify(projectConfig.locale.pagefindTranslations)}`
 	: '';

package/src/components/SitePage.astro

@@ -115,6 +115,7 @@ const hasTables = allContentBlocks.some((block) => (
 ));
 const hasImageStack = allContentBlocks.some((block) => (
 	block.type === 'image-stack'
+	|| (block.type === 'html' && block.html.includes('data-norna-managed-image='))
 ));
 const hasPrioritizableImage = (section: ResolvedSection) => section.contentBlocks.some((block) => (
 	block.type === 'image-stack'

package/src/components/SiteSection.astro

@@ -109,6 +109,7 @@ const bodyWidth = {
 };
 const hasMedia = flattenContentBlocks(section.contentBlocks).some((block) => (
 	block.type === 'image-stack'
+	|| (block.type === 'html' && block.html.includes('data-norna-managed-image='))
 	|| block.type === 'image-carousel'
 	|| (block.type === 'card-list' && block.cards.some((card) => card.image))
 ));

package/src/content.config.ts

@@ -29,10 +29,7 @@ const site = defineCollection({
 		generateId: ({ entry }) => {
 			if (entry === 'content.md') return encodePageEntryId(siteDirLabel, homePageDirectory);
 			const pageEntryDirectory = entry.split('/').slice(1, -1).join('/');
-			const pageDirectory = pageEntryDirectory
-				.split('/')
-				.filter((segment) => segment !== 'pages')
-				.join('/pages/');
+			const pageDirectory = pageEntryDirectory;
 			return encodePageEntryId(siteDirLabel, parsePageDirectoryPath(pageDirectory, `page directory pages/${pageEntryDirectory}`).pageDirectory);
 		},
 	}),

package/src/lib/imagePresentation.ts

@@ -5,6 +5,9 @@ export type ManagedImage = {
 	src?: string;
 	alt?: string;
 	caption?: string;
+	title?: string;
+	href?: string;
+	linkTitle?: string;
 };
 
 type GeneratedImageWithDimensions = NonNullable<ReturnType<typeof getGeneratedImage>> & {

package/src/lib/markdownImages.ts

@@ -0,0 +1,101 @@
+import { parseFragment, serializeOuter, type DefaultTreeAdapterMap } from 'parse5';
+import { getPageImageSourceKey } from '../../scripts/lib/site-conventions.mjs';
+import { getGeneratedImage, getImageAttributes, getImageInspectionAttributes } from './generatedImages';
+import { getImageClass, getImageLoadingProps, getManagedImageSizes } from './imagePresentation';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+
+type Node = DefaultTreeAdapterMap['node'];
+type Element = DefaultTreeAdapterMap['element'];
+const isElement = (node: Node): node is Element => 'tagName' in node;
+const attribute = (node: Element, name: string) => node.attrs.find((attr) => attr.name === name)?.value;
+const meaningfulChildren = (node: Element) => node.childNodes.filter((child) => child.nodeName !== '#text' || ('value' in child && child.value.trim()));
+const soleImage = (node: Element): { image: Element; href?: string; linkTitle?: string } | null => {
+	const children = meaningfulChildren(node);
+	if (children.length !== 1 || !isElement(children[0])) return null;
+	const child = children[0];
+	if (child.tagName === 'img' && attribute(child, 'data-norna-managed-image')) return { image: child };
+	if (child.tagName === 'a') {
+		const nested = soleImage(child);
+		if (nested) return { image: nested.image, href: attribute(child, 'href'), linkTitle: attribute(child, 'title') };
+	}
+	return null;
+};
+
+// Promote only top-level, single-image paragraphs to the shared Astro stack.
+// Nested images stay in their original list, quote, table, details or text.
+export const splitMarkdownImages = (html: string, pageDirectory: string) => {
+	if (!html.includes('data-norna-managed-image=')) return [{ type: 'html' as const, html }];
+	const fragment = parseFragment(html);
+	const result: Array<{ type: 'html'; html: string } | { type: 'image-stack'; images: Array<{ image: string; src: string; alt: string; title?: string; href?: string; linkTitle?: string }> }> = [];
+	let pending = '';
+	const flush = () => { if (pending.trim()) result.push({ type: 'html', html: pending }); pending = ''; };
+	const markSource = (node: Node) => {
+		if (!isElement(node)) return;
+		const marker = node.attrs.find((attr) => attr.name === 'data-norna-managed-image');
+		if (marker) marker.value = getPageImageSourceKey(pageDirectory, marker.value);
+		for (const child of node.childNodes) markSource(child);
+	};
+	for (const node of fragment.childNodes) {
+		const standalone = isElement(node) && node.tagName === 'p' ? soleImage(node) : null;
+		if (standalone) {
+			flush();
+			const name = attribute(standalone.image, 'data-norna-managed-image')!;
+			result.push({ type: 'image-stack', images: [{ image: name, src: getPageImageSourceKey(pageDirectory, name), alt: attribute(standalone.image, 'alt') ?? '', title: attribute(standalone.image, 'title'), href: standalone.href, linkTitle: standalone.linkTitle }] });
+		} else {
+			markSource(node);
+			pending += serializeOuter(node);
+		}
+	}
+	flush();
+	return result;
+};
+
+const escapeAttribute = (value: unknown) => String(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const attributes = (values: Record<string, unknown>) => Object.entries(values).filter(([, value]) => value !== undefined && value !== null).map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`).join('');
+
+export const renderNestedMarkdownImages = (html: string, title: string, width: { desktop: number; mobile: number }) => {
+	if (!html.includes('data-norna-managed-image=')) return html;
+	const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+	const edits: Array<{ start: number; end: number; html: string }> = [];
+	const renderImage = (node: Element, standalone = false, href?: string, linkTitle?: string) => {
+		const src = attribute(node, 'data-norna-managed-image')!;
+		if (!getGeneratedImage(src)) throw new Error(`Managed Markdown image is missing from the generated manifest: ${src}. Run Norna's image preparation after correcting the source file.`);
+		const alt = attribute(node, 'alt') ?? '';
+		const imageClass = standalone ? ['managed-image', getImageClass({ image: src })].filter(Boolean).join(' ') : 'managed-markdown-inline';
+		const image = `<img${attributes({ ...getImageAttributes(src, getManagedImageSizes(width)), class: imageClass, alt, title: attribute(node, 'title'), ...getImageLoadingProps(false) })}>`;
+		if (!standalone) return image;
+		const inspection = getImageInspectionAttributes(src);
+		const link = attributes({
+			class: 'managed-image-inspection-link', href: href ?? inspection.href, title: linkTitle,
+			'aria-label': href === undefined ? projectConfig.locale.labels.inspectImage.replace('{description}', alt || title) : undefined,
+			'data-image-inspection-trigger': href === undefined ? '' : undefined,
+			'data-image-intrinsic-width': inspection.width, 'data-image-intrinsic-height': inspection.height,
+			'data-image-inspection-scalable': inspection.scalable ? 'true' : undefined,
+			style: inspection.width && inspection.height ? `--managed-image-intrinsic-width: ${inspection.width}px; --managed-image-aspect-ratio: ${inspection.width / inspection.height}` : undefined,
+		});
+		// The same Lucide Maximize2 affordance used by ImageStack.astro; this
+		// fragment stays inside the authored Markdown container.
+		const affordance = href === undefined ? '<span class="managed-image-inspection-affordance" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 3h6v6"/><path d="m21 3-7 7"/><path d="m3 21 7-7"/><path d="M9 21H3v-6"/></svg></span>' : '';
+		return `<div class="image-stack managed-markdown-standalone content-block-note-lane-boundary"><figure class="managed-image-item"><div class="managed-image-frame"><a${link}>${image}${affordance}</a></div></figure></div>`;
+	};
+	const visit = (node: Node) => {
+		if (!isElement(node)) return;
+		const location = node.sourceCodeLocation;
+		if (location && (node.tagName === 'p' || node.tagName === 'li')) {
+			const standalone = soleImage(node);
+			if (standalone) {
+				const start = node.tagName === 'li' ? location.startTag!.endOffset : location.startOffset;
+				const end = node.tagName === 'li' ? (location.endTag?.startOffset ?? location.endOffset) : location.endOffset;
+				edits.push({ start, end, html: renderImage(standalone.image, true, standalone.href, standalone.linkTitle) });
+				return;
+			}
+		}
+		if (location && node.tagName === 'img' && attribute(node, 'data-norna-managed-image')) {
+			edits.push({ start: location.startOffset, end: location.endOffset, html: renderImage(node) });
+			return;
+		}
+		for (const child of node.childNodes) visit(child);
+	};
+	for (const node of fragment.childNodes) visit(node);
+	return edits.sort((a, b) => b.start - a.start).reduce((result, edit) => result.slice(0, edit.start) + edit.html + result.slice(edit.end), html);
+};