@janga/norna 0.7.23 → 0.7.24

package/scripts/lib/site-link-graph.mjs

@@ -2,6 +2,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	createPageAliasModel,
+	generatedSiteRoutes,
 } from './page-aliases.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
 import {
@@ -117,6 +118,9 @@ const createPageRecord = ({ contentFile, data = {}, document }) => {
 		anchors,
 		contentFile,
 		document,
+		navigation: {
+			listed: data.navigation?.listed ?? true,
+		},
 		pathname,
 		title: document.pageTitle?.title ?? contentFile.pageId,
 	};
@@ -140,7 +144,13 @@ const looksLikePublicFile = (pathname) => {
 	return (pathname.split('/').at(-1) ?? '').includes('.');
 };
 
-export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles = [] }) => {
+export const createSiteLinkGraph = ({
+	siteStructure,
+	pageDocuments,
+	publicFiles = [],
+	generatedRoutes,
+}) => {
+	const activeGeneratedRoutes = generatedRoutes ?? generatedSiteRoutes;
 	const documentsByDirectory = new Map(pageDocuments.map(({ contentFile, data, document }) => [
 		contentFile.pageDirectory,
 		{ contentFile, data, document },
@@ -167,7 +177,11 @@ export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles
 		categories: siteStructure.categories,
 		pages,
 		publicFiles,
+		generatedRoutes: activeGeneratedRoutes,
 	});
+	const generatedRoutesByPathname = new Map(
+		activeGeneratedRoutes.map((route) => [route.pathname, route]),
+	);
 
 	const references = [];
 	const referencesByTarget = new Map();
@@ -249,6 +263,18 @@ export const createSiteLinkGraph = ({ siteStructure, pageDocuments, publicFiles
 				continue;
 			}
 
+			const generatedRoute = generatedRoutesByPathname.get(
+				target.pageLookupPathname ?? target.pathname,
+			);
+			if (generatedRoute && !target.fragment) {
+				reference.resolution = {
+					kind: 'generated-route',
+					pathname: generatedRoute.pathname,
+					route: generatedRoute,
+				};
+				continue;
+			}
+
 			const targetCategory = target.pageLookupPathname
 				? categoriesByPathname.get(target.pageLookupPathname)
 				: null;
@@ -320,7 +346,12 @@ export const getSiteLinkGraph = async (options = {}) => {
 		readPublicFiles(options.publicDir ?? sitePublicDir),
 	]);
 
-	return createSiteLinkGraph({ pageDocuments, publicFiles, siteStructure });
+	return createSiteLinkGraph({
+		pageDocuments,
+		publicFiles,
+		siteStructure,
+		generatedRoutes: options.generatedRoutes,
+	});
 };
 
 export const getSitePublicFiles = async (publicDir = sitePublicDir) => readPublicFiles(publicDir);

package/scripts/lib/site-navigation-tree.mjs

@@ -0,0 +1,85 @@
+export const getSiteNavigationTree = (entries) => {
+	const nodes = new Map();
+	const roots = [];
+
+	for (const entry of entries) {
+		nodes.set(entry.node.pagePath, { ...entry, children: [] });
+	}
+
+	for (const entry of entries) {
+		const node = nodes.get(entry.node.pagePath);
+		if (!node) continue;
+
+		if (entry.node.isHome || entry.node.parentPagePath === null) {
+			roots.push(node);
+			continue;
+		}
+
+		const parent = nodes.get(entry.node.parentPagePath);
+		if (!parent) {
+			throw new Error(`Site node "${entry.node.pagePath}" has no parent node "${entry.node.parentPagePath}".`);
+		}
+
+		parent.children.push(node);
+	}
+
+	return roots;
+};
+
+export const getListedSiteNavigationTree = (entries) => {
+	const filterListed = (nodes) => nodes.flatMap((node) => {
+		if (!node.node.isHome && !node.node.navigation.listed) return [];
+		const children = filterListed(node.children);
+		if (node.node.kind === 'category' && children.length === 0) return [];
+		return [{ ...node, children }];
+	});
+
+	return filterListed(getSiteNavigationTree(entries));
+};
+
+export const getFirstPageInNavigationNode = (node) => {
+	if (node.node.kind === 'page') return node.node;
+
+	for (const child of node.children) {
+		const page = getFirstPageInNavigationNode(child);
+		if (page) return page;
+	}
+
+	return null;
+};
+
+export const flattenSiteNavigationTree = (nodes) => nodes.flatMap((node) => [
+	node,
+	...flattenSiteNavigationTree(node.children),
+]);
+
+export const getSequentialPageNavigation = (nodes, currentPagePath) => {
+	const activeRoot = nodes.find((root) => (
+		flattenSiteNavigationTree([root]).some(({ node }) => node.pagePath === currentPagePath)
+	));
+	if (!activeRoot) return { previous: null, next: null };
+
+	const pages = flattenSiteNavigationTree([activeRoot])
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+	const currentIndex = pages.findIndex(({ pagePath }) => pagePath === currentPagePath);
+	if (currentIndex < 0) return { previous: null, next: null };
+
+	return {
+		previous: pages[currentIndex - 1] ?? null,
+		next: pages[currentIndex + 1] ?? null,
+	};
+};
+
+export const getDirectChildPages = (nodes, currentPagePath) => {
+	const current = flattenSiteNavigationTree(nodes)
+		.find(({ node }) => node.pagePath === currentPagePath);
+	if (!current) return [];
+	const children = current.node.isHome
+		? nodes.filter(({ node }) => !node.isHome)
+		: current.children;
+
+	return children
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+};

package/scripts/lib/social-image-assets.mjs

@@ -0,0 +1,30 @@
+import { getPublicAssetInspection } from './logo-assets.mjs';
+import {
+	socialImageAssetDefinitions,
+	socialImageAssetFilenames,
+} from './public-asset-conventions.mjs';
+import { sitePublicLabel } from './site-paths.mjs';
+
+const definitionsByFilename = new Map(
+	socialImageAssetDefinitions.map((definition) => [definition.filename, definition]),
+);
+
+export const getSocialImageAssets = () => getPublicAssetInspection().socialImages
+	.map((filename) => ({
+		...definitionsByFilename.get(filename),
+		filename,
+		href: `/${filename}`,
+	}));
+
+export const getSocialImageAsset = () => {
+	const assets = getSocialImageAssets();
+
+	if (assets.length > 1) {
+		throw new Error([
+			`Found multiple social sharing images in ${sitePublicLabel}. Keep exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+			...assets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
+		].join('\n'));
+	}
+
+	return assets[0] ?? null;
+};

package/scripts/lib/theme-presets.mjs

@@ -4,7 +4,7 @@ import { resolveThemeProfileRecipe } from './theme-profiles.mjs';
 
 export const themePresetRecipes = Object.freeze({
 	portfolio: Object.freeze({
-		color: 'near-monochrome-dark',
+		color: 'near-monochrome-adaptive',
 		typography: 'restrained-sans',
 		rhythm: 'balanced',
 		geometry: 'image-led',
@@ -231,7 +231,7 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'blocks:',
 		'  cardList:',
 		'    # Alternatives: text, narrow, normal, wide.',
-		'    # A width written in a norna-card-list block overrides this default.',
+		'    # A width written in a card-list block overrides this default.',
 		`    width: ${blocks.cardList.width}`,
 		'',
 		'typography:',

package/scripts/lib/theme-profiles.mjs

@@ -2,10 +2,6 @@ import { freezeDeep, mergeDeep } from './object.mjs';
 
 export const themeProfileDefinitions = freezeDeep({
 	color: {
-		'near-monochrome-dark': {
-			appearance: { default: 'dark' },
-			palette: 'near-monochrome',
-		},
 		'near-monochrome-adaptive': {
 			appearance: { default: 'system' },
 			palette: 'near-monochrome',

package/scripts/move-site-page.mjs

@@ -0,0 +1,256 @@
+import { randomUUID } from 'node:crypto';
+import {
+	access,
+	mkdir,
+	readFile,
+	rename,
+	rm,
+	rmdir,
+	writeFile,
+} from 'node:fs/promises';
+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,
+} 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 fileExists = async (filePath) => access(filePath).then(() => true, () => false);
+
+const writeFileAtomically = async (filePath, source, mode) => {
+	const temporaryPath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.norna-${process.pid}-${randomUUID()}.tmp`,
+	);
+	try {
+		await writeFile(temporaryPath, source, { mode: mode & 0o777 });
+		await rename(temporaryPath, filePath);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+};
+
+const assertSourcesUnchanged = async (plan) => {
+	for (const file of plan.sourceFiles) {
+		const currentSource = await readFile(file.contentPath, 'utf8');
+		if (currentSource !== file.source) {
+			throw new Error([
+				`Page move stopped because ${file.contentLabel} changed after the plan was created.`,
+				'Run the command again to build a fresh plan. No file was changed.',
+			].join('\n'));
+		}
+	}
+};
+
+const assertFinalSite = async () => {
+	const structure = await getSiteStructure();
+	const graph = await getSiteLinkGraph({ siteStructure: structure });
+	if (graph.diagnostics.length === 0) return;
+	throw new Error([
+		'Post-move link validation failed.',
+		...graph.diagnostics.flatMap((diagnostic) => [
+			`- ${diagnostic.message}`,
+			...(diagnostic.fix ? [`  Fix: ${diagnostic.fix}`] : []),
+		]),
+	].join('\n'));
+};
+
+const applyPlan = async (plan) => {
+	await assertSourcesUnchanged(plan);
+	let collectionCreated = false;
+	let directoryMoved = false;
+	let fileWritten = false;
+
+	try {
+		if (plan.mode === 'move') {
+			if (!plan.destinationCollectionExists) {
+				await mkdir(plan.destinationCollectionDirectory);
+				collectionCreated = true;
+			}
+			try {
+				await rename(plan.sourceDirectory, plan.destinationDirectory);
+				directoryMoved = true;
+			} catch (error) {
+				if (error?.code === 'EXDEV') {
+					throw new Error('Page directories must stay on one filesystem so Norna can move the complete subtree atomically.');
+				}
+				throw error;
+			}
+		}
+
+		for (const change of plan.fileChanges) {
+			await writeFileAtomically(change.finalPath, change.updatedSource, change.mode);
+			fileWritten = true;
+		}
+		await assertFinalSite();
+	} catch (error) {
+		const changesStarted = directoryMoved || fileWritten;
+		const rollbackErrors = [];
+		if (directoryMoved) {
+			try {
+				await rename(plan.destinationDirectory, plan.sourceDirectory);
+				directoryMoved = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore the page directory: ${rollbackError.message}`);
+			}
+		}
+
+		for (const change of plan.fileChanges) {
+			try {
+				const restorePath = directoryMoved && change.finalPath !== change.originalPath
+					? change.finalPath
+					: change.originalPath;
+				await writeFileAtomically(restorePath, change.originalSource, change.mode);
+			} catch (rollbackError) {
+				rollbackErrors.push(`Could not restore ${change.contentLabel}: ${rollbackError.message}`);
+			}
+		}
+
+		if (collectionCreated && !directoryMoved) {
+			try {
+				await rmdir(plan.destinationCollectionDirectory);
+			} catch (rollbackError) {
+				if (rollbackError?.code !== 'ENOENT' && rollbackError?.code !== 'ENOTEMPTY') {
+					rollbackErrors.push(`Could not remove the newly created pages directory: ${rollbackError.message}`);
+				}
+			}
+		}
+
+		throw new Error([
+			error instanceof Error ? error.message : String(error),
+			rollbackErrors.length === 0
+				? (changesStarted
+					? 'The original page directory and content files were restored.'
+					: 'No source file was changed.')
+				: 'Rollback was incomplete. Inspect these paths before running page:move again:',
+			...rollbackErrors.map((message) => `- ${message}`),
+		].join('\n'));
+	}
+};
+
+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 applyPlan(plan);
+	console.log(`\nPage move completed: ${plan.from} -> ${plan.to}`);
+};
+
+try {
+	await main();
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/scripts/review-navigation.mjs

@@ -0,0 +1,32 @@
+import {
+	formatNavigationReviewText,
+	getNavigationReview,
+	parseNavigationReviewArgs,
+} from './lib/navigation-review.mjs';
+
+const usage = `
+Usage: norna navigation:review [--format text|json]
+
+Read the selected site and report its page hierarchy, heading outlines,
+internal page links, effective navigation modes, and structural review prompts.
+No files are changed.
+`.trim();
+
+try {
+	const { format, help } = parseNavigationReviewArgs(process.argv.slice(2));
+	if (help) {
+		console.log(usage);
+	} else {
+		const { projectConfig } = await import('./lib/project-config.mjs');
+		const review = await getNavigationReview({
+			requestedNavigationMode: projectConfig.navigation.mode,
+		});
+		process.stdout.write(format === 'json'
+			? `${JSON.stringify(review, null, 2)}\n`
+			: formatNavigationReviewText(review));
+		if (review.errors.length > 0) process.exitCode = 1;
+	}
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+}

package/scripts/sync-content-sections.mjs

@@ -21,10 +21,16 @@ import {
 import { getSiteStructure } from './lib/site-structure.mjs';
 import { readImageDimensions } from './lib/image-dimensions.mjs';
 import { parsePageMarkdownSource } from './lib/page-markdown.mjs';
+import {
+	getDirectChildPages,
+	getListedSiteNavigationTree,
+} from './lib/site-navigation-tree.mjs';
 import {
 	createSiteLinkGraph,
 	getSitePublicFiles,
 } from './lib/site-link-graph.mjs';
+import { getGeneratedSiteRoutes } from './lib/page-aliases.mjs';
+import projectConfig from './lib/project-config.mjs';
 import {
 	siteThemeLabel,
 	siteThemePath,
@@ -363,6 +369,22 @@ for (const contentFile of contentFiles) {
 			});
 		}
 
+		for (const error of section.calloutErrors) {
+			addSectionIssue(contentFile, section, {
+				severity: 'error',
+				message: error.message,
+				fix: error.fix,
+			});
+		}
+
+		for (const error of section.codeFenceErrors) {
+			addSectionIssue(contentFile, section, {
+				severity: 'error',
+				message: error.message,
+				fix: error.fix,
+			});
+		}
+
 		for (const reference of section.managedImages) {
 			managedImageReferences.push({ contentFile, section, reference });
 		}
@@ -379,6 +401,41 @@ for (const contentFile of contentFiles) {
 	});
 }
 
+const contentContextByPageDirectory = new Map(contentFileContexts.map((context) => [
+	context.contentFile.pageDirectory,
+	context,
+]));
+const listedNavigationTree = getListedSiteNavigationTree(siteStructure.nodes.map((node) => {
+	const context = contentContextByPageDirectory.get(node.pageDirectory);
+	return {
+		node: {
+			...node,
+			navigation: {
+				listed: node.kind === 'category'
+					? true
+					: context?.frontmatterData.navigation?.listed ?? true,
+			},
+		},
+	};
+}));
+
+for (const context of contentFileContexts) {
+	const childPages = getDirectChildPages(listedNavigationTree, context.contentFile.pagePath);
+	if (childPages.length > 0) continue;
+
+	for (const section of context.sections) {
+		if (!context.validSections.has(section)) continue;
+		for (const block of section.blocks) {
+			if (block.type !== 'page-list') continue;
+			addSectionIssue(context.contentFile, section, {
+				severity: 'error',
+				message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
+				fix: 'Add a listed direct child page or remove the block.',
+			});
+		}
+	}
+}
+
 const siteLinkGraph = createSiteLinkGraph({
 	pageDocuments: contentFileContexts.map(({ contentFile, frontmatterData, page }) => ({
 		contentFile,
@@ -387,9 +444,15 @@ const siteLinkGraph = createSiteLinkGraph({
 	})),
 	publicFiles: await getSitePublicFiles(),
 	siteStructure,
+	generatedRoutes: getGeneratedSiteRoutes({ searchEnabled: projectConfig.search.enabled }),
 });
 for (const issue of siteLinkGraph.diagnostics) {
-	addContentIssue(issue.reference?.sourceContentFile ?? issue.contentFile, issue);
+	const issueContentFile = issue.reference?.sourceContentFile ?? issue.contentFile;
+	if (issueContentFile) {
+		addContentIssue(issueContentFile, issue);
+	} else {
+		addIssue(issue);
+	}
 }
 
 const imageSyncPlan = createImageSyncPlan({
@@ -441,7 +504,7 @@ for (const context of contentFileContexts) {
 			addSectionIssue(contentFile, section, {
 				severity: 'warning',
 				message: `Markdown image "${reference.target}" references a local image that is not managed by Norna.`,
-				fix: 'Use a norna-image-stack, norna-image-carousel, or norna-card-list block for site images that should be validated, processed and synced.',
+				fix: 'Use an image-stack, image-carousel, or card-list block for site images that should be validated, processed and synced.',
 			});
 		}
 
@@ -457,8 +520,8 @@ for (const context of contentFileContexts) {
 			if (block.type === 'image-carousel' && block.images.length < 2) {
 				addSectionIssue(contentFile, section, {
 					severity: 'error',
-					message: `norna-image-carousel on line ${block.line} contains ${block.images.length} image. A carousel needs at least two images.`,
-					fix: 'Add another image entry, or use norna-image-stack for a single image.',
+					message: `image-carousel on line ${block.line} contains ${block.images.length} image. An image carousel needs at least two images.`,
+					fix: 'Add another image entry, or use image-stack for a single image.',
 				});
 			}
 		}

package/scripts/sync-site-public.mjs

@@ -10,7 +10,10 @@ import {
 } from './lib/site-paths.mjs';
 import { getSiteStructure } from './lib/site-structure.mjs';
 
-const keepAstroPublicEntries = new Set(['images']);
+const keepAstroPublicEntries = new Set([
+	'images',
+	...(projectConfig.search.enabled ? ['pagefind'] : []),
+]);
 
 const readDirectory = async (directory) => {
 	try {
@@ -25,11 +28,27 @@ const readDirectory = async (directory) => {
 };
 
 const sourceEntries = await readDirectory(sitePublicDir);
-const sitemapConflict = sourceEntries.find(({ name }) => name.toLowerCase() === sitemapFilename);
-if (sitemapConflict) {
+const generatedPublicFiles = [
+	{
+		filename: sitemapFilename,
+		explanation: `Norna generates ${sitemapFilename} from the public page tree and the URL in site/config.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}/${sitemapConflict.name} conflicts with Norna's generated ${sitemapFilename}.`,
-		`Remove that source file. Norna generates ${sitemapFilename} from the public page tree and the URL in site/config.yaml.`,
+		`${sitePublicLabel}/${conflict.name} conflicts with Norna's generated ${generatedFile.filename}.`,
+		`Remove that source file. ${generatedFile.explanation}`,
 	].join('\n'));
 }
 

package/src/components/CodeBlockCopyScript.astro

@@ -65,10 +65,15 @@ const labels = {
 			const pre = code.parentElement;
 			if (!pre || pre.parentElement?.classList.contains('code-block')) return;
 
-			const wrapper = document.createElement('div');
-			wrapper.className = 'code-block';
-			pre.before(wrapper);
-			wrapper.append(pre);
+			const codeExample = pre.parentElement?.classList.contains('norna-code-example')
+				? pre.parentElement
+				: null;
+			const wrapper = codeExample ?? document.createElement('div');
+			wrapper.classList.add('code-block');
+			if (!codeExample) {
+				pre.before(wrapper);
+				wrapper.append(pre);
+			}
 
 			const button = template.content.firstElementChild?.cloneNode(true);
 			if (!(button instanceof HTMLButtonElement)) return;