@janga/norna 0.7.23 → 0.7.25

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

@@ -4,7 +4,7 @@ const field = (description, options = {}) => Object.freeze({ description, ...opt
 const value = (title, description) => Object.freeze({ title, description });
 
 export const nornaMarkdownBlockDefinitions = Object.freeze({
-	'norna-image-stack': Object.freeze({
+	'image-stack': Object.freeze({
 		description: 'Display one or more managed images in a vertical stack.',
 		documentation: documentationLink('Image stack reference', 'content.md', 'image-stack'),
 		item: Object.freeze({
@@ -15,7 +15,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 			}),
 		}),
 	}),
-	'norna-image-carousel': Object.freeze({
+	'image-carousel': Object.freeze({
 		description: 'Display two or more managed images in an interactive carousel.',
 		documentation: documentationLink('Image carousel reference', 'content.md', 'image-carousel'),
 		item: Object.freeze({
@@ -26,7 +26,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 			}),
 		}),
 	}),
-	'norna-card-list': Object.freeze({
+	'card-list': Object.freeze({
 		description: 'Display a structured list of cards.',
 		documentation: documentationLink('Card list reference', 'content.md', 'card-list'),
 		options: Object.freeze({
@@ -73,25 +73,45 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 			}),
 		}),
 	}),
+	'page-list': Object.freeze({
+		description: 'Display the current page\'s listed direct child pages in navigation order.',
+		documentation: documentationLink('Child page list reference', 'content.md', 'child-page-list'),
+	}),
 });
 
 export const nornaBlockTypes = new Set(Object.keys(nornaMarkdownBlockDefinitions));
 
+const renamedNornaBlockTypes = Object.freeze({
+	'norna-image-stack': 'image-stack',
+	'norna-image-carousel': 'image-carousel',
+	'norna-carousel': 'image-carousel',
+	carousel: 'image-carousel',
+	'norna-card-list': 'card-list',
+	'norna-page-list': 'page-list',
+});
+
 const blockTypeLabels = {
-	'norna-image-stack': 'norna-image-stack',
-	'norna-image-carousel': 'norna-image-carousel',
-	'norna-card-list': 'norna-card-list',
+	'image-stack': 'image-stack',
+	'image-carousel': 'image-carousel',
+	'card-list': 'card-list',
+	'page-list': 'page-list',
 };
 
 const knownBlockTypeList = Array.from(nornaBlockTypes).join(', ');
 const imageNameRegex = /^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$/i;
 const imageStackExample = [
-	'```norna-image-stack',
+	'```image-stack',
 	'- image: filename.jpg',
 	'```',
 ].join('\n');
+const carouselExample = [
+	'```image-carousel',
+	'- image: first.jpg',
+	'- image: second.jpg',
+	'```',
+].join('\n');
 const cardListExample = [
-	'```norna-card-list',
+	'```card-list',
 	'layout: image-top',
 	'flow: grid',
 	'size: m',
@@ -103,7 +123,17 @@ const cardListExample = [
 	'  badge-text: Recommended',
 	'```',
 ].join('\n');
-const cardListDefinition = nornaMarkdownBlockDefinitions['norna-card-list'];
+const pageListExample = [
+	'```page-list',
+	'```',
+].join('\n');
+const blockExamples = Object.freeze({
+	'image-stack': imageStackExample,
+	'image-carousel': carouselExample,
+	'card-list': cardListExample,
+	'page-list': pageListExample,
+});
+const cardListDefinition = nornaMarkdownBlockDefinitions['card-list'];
 const cardListLayouts = new Set(Object.keys(cardListDefinition.options.layout.values));
 const cardListFlows = new Set(Object.keys(cardListDefinition.options.flow.values));
 const cardListSizes = new Set(Object.keys(cardListDefinition.options.size.values));
@@ -120,18 +150,20 @@ const fail = (message, options) => {
 };
 
 const getUnknownNornaBlockMessage = (type) => [
-	`Unknown Norna block "${type}". Use one of: ${knownBlockTypeList}.`,
+	renamedNornaBlockTypes[type]
+		? `Norna block "${type}" was renamed to "${renamedNornaBlockTypes[type]}".`
+		: `Unknown Norna block "${type}". Use one of: ${knownBlockTypeList}.`,
 	type === 'norna-gallery-stack'
-		? 'Use norna-image-stack for one or more stacked images.'
+		? 'Use image-stack for one or more stacked images.'
 		: null,
-	type === 'norna-carousel'
-		? 'Use norna-image-carousel for an image carousel.'
+	type === 'norna-image-carousel' || type === 'norna-carousel' || type === 'carousel'
+		? 'Use image-carousel for an image carousel.'
 		: null,
 	type === 'norna-image'
-		? 'Use norna-image-stack for a single image or a stacked list of images.'
+		? 'Use image-stack for a single image or a stacked list of images.'
 		: null,
 	'Example:',
-	imageStackExample,
+	blockExamples[renamedNornaBlockTypes[type] ?? type] ?? imageStackExample,
 ].filter(Boolean).join(' ');
 
 const decodeScalar = (value) => {
@@ -229,17 +261,23 @@ export const getOpenMarkdownFenceAtLine = (markdown, lineIndex) => {
 };
 
 const getNornaLineAttempt = (line) => {
-	const match = line.match(/^ {0,3}([`~]{0,2})(norna-[a-z0-9-]+)\s*$/);
+	const match = line.match(/^ {0,3}([`~]{0,2})([a-z][a-z0-9-]+)\s*$/);
 	if (!match) return null;
+	const marker = match[1];
+	const type = match[2];
+	const isNamespacedAttempt = type.startsWith('norna-');
+	if (!isNamespacedAttempt && !nornaBlockTypes.has(type) && !renamedNornaBlockTypes[type]) return null;
+	if (!marker && type === 'carousel') return null;
 
 	return {
-		marker: match[1],
-		type: match[2],
+		marker,
+		type,
 	};
 };
 
 const getNornaFenceStartMessage = (type, marker = '') => {
-	const example = type === 'norna-card-list' ? cardListExample : `\`\`\`${type}\n- image: filename.jpg\n\`\`\``;
+	const supportedType = renamedNornaBlockTypes[type] ?? type;
+	const example = blockExamples[supportedType] ?? imageStackExample;
 	if (marker) {
 		return `Invalid Norna block start for "${type}". Use three backticks or three tildes. Example:\n${example}`;
 	}
@@ -317,7 +355,7 @@ const scanMarkdownFencedBlocks = (markdown, options = {}) => {
 			}
 		}
 
-		const isNornaLike = type.startsWith('norna-');
+		const isNornaLike = type.startsWith('norna-') || nornaBlockTypes.has(type) || Boolean(renamedNornaBlockTypes[type]);
 		if (closingIndex === -1) {
 			if (isNornaLike) {
 				errors.push({
@@ -350,7 +388,7 @@ const scanMarkdownFencedBlocks = (markdown, options = {}) => {
 			} else {
 				errors.push({
 					blockType: type,
-					code: 'unknown-norna-block',
+					code: renamedNornaBlockTypes[type] ? 'renamed-norna-block' : 'unknown-norna-block',
 					line: lineNumber,
 					source,
 					message: failMessage(getUnknownNornaBlockMessage(type), { ...options, line: lineNumber }),
@@ -406,10 +444,10 @@ const parseImageListBlock = (source, options = {}) => {
 	}
 
 	if (images.length === 0) {
-		fail(`${options.type} must contain at least one image. Example:\n${imageStackExample}`, options);
+		fail(`${options.type} must contain at least one image. Example:\n${blockExamples[options.type]}`, options);
 	}
 
-	return { type: options.type === 'norna-image-carousel' ? 'image-carousel' : 'image-stack', images };
+	return { type: options.type === 'image-carousel' ? 'image-carousel' : 'image-stack', images };
 };
 
 const parseCardListBlock = (source, options = {}) => {
@@ -517,15 +555,23 @@ const parseCardListBlock = (source, options = {}) => {
 	return { type: 'card-list', layout, flow, size, width, cards };
 };
 
+const parsePageListBlock = (source, options = {}) => {
+	if (source.trim()) {
+		fail(`${options.type} does not accept options or items. Leave the block empty. Example:\n${pageListExample}`, options);
+	}
+
+	return { type: 'page-list' };
+};
+
 export const parseNornaMarkdownBlock = (type, source, options = {}) => {
 	if (!nornaBlockTypes.has(type)) {
 		fail(getUnknownNornaBlockMessage(type), options);
 	}
 
 	const parseOptions = { ...options, type: blockTypeLabels[type] };
-	return type === 'norna-card-list'
-		? parseCardListBlock(source, parseOptions)
-		: parseImageListBlock(source, parseOptions);
+	if (type === 'card-list') return parseCardListBlock(source, parseOptions);
+	if (type === 'page-list') return parsePageListBlock(source, parseOptions);
+	return parseImageListBlock(source, parseOptions);
 };
 
 const getLineNumber = (source, index) => source.slice(0, index).split(/\r?\n/).length;
@@ -561,6 +607,97 @@ export const extractNornaMarkdownBlockDiagnostics = (markdown, options = {}) =>
 	return { blocks, errors };
 };
 
+const stripRenderedTags = (value) => value.replace(/<[^>]*>/g, '');
+const decodeRenderedEntities = (value) => value
+	.replace(/&amp;/g, '&')
+	.replace(/&lt;/g, '<')
+	.replace(/&gt;/g, '>')
+	.replace(/&quot;/g, '"')
+	.replace(/&#39;/g, "'");
+const normalizeRenderedBlockSource = (value) => value.replace(/\r\n?/g, '\n').trim();
+
+/**
+ * Splits rendered HTML at Norna markers. During an Astro content hot reload,
+ * custom code nodes can occasionally arrive as highlighted code instead of
+ * their marker; match that output against the already validated source block.
+ *
+ * @template {{ type: string, source?: string }} Block
+ * @param {string} html
+ * @param {Block[]} blocks
+ * @returns {Array<{ type: 'html', html: string } | Block>}
+ */
+export const splitNornaRenderedBlocks = (html, blocks) => {
+	const markerRegex = /<norna-block\s+data-index="(\d+)"\s*><\/norna-block>/g;
+	const markerMatches = [...html.matchAll(markerRegex)];
+	let replacements;
+
+	if (markerMatches.length > 0) {
+		const seen = new Set();
+		replacements = markerMatches.map((match) => {
+			const blockIndex = Number.parseInt(match[1] ?? '', 10);
+			if (!blocks[blockIndex]) {
+				throw new Error(`Rendered Norna block ${blockIndex + 1} has no matching parsed block.`);
+			}
+			if (seen.has(blockIndex)) {
+				throw new Error(`Rendered Norna block ${blockIndex + 1} appears more than once.`);
+			}
+			seen.add(blockIndex);
+			return { match, blockIndex };
+		});
+
+		if (seen.size !== blocks.length) {
+			throw new Error(`Rendered Markdown contains ${seen.size} Norna block markers, but ${blocks.length} blocks were parsed.`);
+		}
+	} else {
+		const codeRegex = /<pre\b[^>]*>\s*<code\b[^>]*>([\s\S]*?)<\/code>\s*<\/pre>/g;
+		const candidates = [...html.matchAll(codeRegex)].map((match) => ({
+			match,
+			source: normalizeRenderedBlockSource(decodeRenderedEntities(stripRenderedTags(match[1] ?? ''))),
+		}));
+		const solutions = [];
+		const findSolutions = (blockIndex, candidateIndex, selected) => {
+			if (solutions.length > 1) return;
+			if (blockIndex === blocks.length) {
+				solutions.push([...selected]);
+				return;
+			}
+
+			const source = normalizeRenderedBlockSource(blocks[blockIndex]?.source ?? '');
+			for (let index = candidateIndex; index < candidates.length; index += 1) {
+				if (candidates[index].source !== source) continue;
+				selected.push(index);
+				findSolutions(blockIndex + 1, index + 1, selected);
+				selected.pop();
+			}
+		};
+		findSolutions(0, 0, []);
+
+		if (solutions.length === 0) {
+			throw new Error(`Rendered Markdown contains 0 Norna block markers, but ${blocks.length} blocks were parsed.`);
+		}
+		if (solutions.length > 1) {
+			throw new Error('Rendered Markdown contains ambiguous plain-code matches for Norna blocks. Restart the local preview to rebuild the Markdown content cache.');
+		}
+
+		replacements = solutions[0].map((candidateIndex, blockIndex) => ({
+			match: candidates[candidateIndex].match,
+			blockIndex,
+		}));
+	}
+
+	const result = [];
+	let cursor = 0;
+	for (const { match, blockIndex } of replacements) {
+		const start = match.index ?? 0;
+		if (start > cursor) result.push({ type: 'html', html: html.slice(cursor, start) });
+		result.push(blocks[blockIndex]);
+		cursor = start + match[0].length;
+	}
+	if (cursor < html.length) result.push({ type: 'html', html: html.slice(cursor) });
+
+	return result.filter((block) => block.type !== 'html' || block.html.trim());
+};
+
 const maskFencedCodeBlocks = (markdown) => {
 	const lines = normalizeLines(markdown);
 	const maskedLines = [];
@@ -631,6 +768,7 @@ export const getNornaBlockImageReferences = (blocks) =>
 					line: card.line ?? block.line,
 				}));
 		}
+		if (block.type === 'page-list') return [];
 
 		return block.images.map((image) => ({
 			...image,

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

@@ -1,17 +1,80 @@
 import { defineMdastPlugin } from 'satteri';
 import { nornaBlockTypes } from './norna-markdown-blocks.mjs';
+import projectConfig from './project-config.mjs';
+import { getSemanticCalloutMarker } from './semantic-callouts.mjs';
 
 const stateKey = 'nornaMarkdownRender';
 
 const getState = (context) => {
 	if (!context.data[stateKey]) {
-		context.data[stateKey] = { blockIndex: 0, regionIndex: 0 };
+		context.data[stateKey] = { blockIndex: 0, calloutIndex: 0, regionIndex: 0 };
 	}
 	return context.data[stateKey];
 };
 
+const calloutLabelKeys = Object.freeze({
+	CAUTION: 'calloutCaution',
+	DANGER: 'calloutDanger',
+	IMPORTANT: 'calloutImportant',
+	NOTE: 'calloutNote',
+	TIP: 'calloutTip',
+	WARNING: 'calloutWarning',
+});
+
+const hasBlockquoteAncestor = (node, context) => {
+	let parent = context.parent(node);
+	while (parent) {
+		if (parent.type === 'blockquote') return true;
+		parent = context.parent(parent);
+	}
+	return false;
+};
+
 export const nornaMarkdownRenderPlugin = defineMdastPlugin({
 	name: 'norna-markdown-render',
+	blockquote(node, context) {
+		const marker = getSemanticCalloutMarker(node);
+		if (
+			!marker
+			|| marker.malformed
+			|| !marker.supported
+			|| marker.rawType !== marker.type
+			|| marker.title
+			|| !marker.hasBody
+			|| hasBlockquoteAncestor(node, context)
+		) return;
+
+		const state = getState(context);
+		const labelKey = calloutLabelKeys[marker.type];
+		const label = projectConfig.locale.labels[labelKey];
+		const labelId = `norna-callout-label-${state.calloutIndex}`;
+		state.calloutIndex += 1;
+
+		context.setProperty(node, 'data', {
+			hName: 'aside',
+			hProperties: {
+				'aria-labelledby': labelId,
+				className: ['norna-callout', `norna-callout-${marker.type.toLowerCase()}`],
+				role: 'note',
+			},
+		});
+
+		if (!marker.firstTextRemainder && marker.firstParagraph.children.length === 1) {
+			context.removeChildAt(node, 0);
+		} else {
+			context.setProperty(marker.firstText, 'value', marker.firstTextRemainder);
+		}
+		context.prependChild(node, {
+			type: 'paragraph',
+			data: {
+				hProperties: {
+					className: ['norna-callout-label'],
+					id: labelId,
+				},
+			},
+			children: [{ type: 'text', value: label }],
+		});
+	},
 	code(node, context) {
 		if (!nornaBlockTypes.has(node.lang)) return;
 

package/scripts/lib/page-aliases.mjs

@@ -1,14 +1,21 @@
 import { getSiteNodePathname } from './site-page-urls.mjs';
 import { sitemapFilename } from './sitemap.mjs';
 
-export const generatedSiteRoutes = Object.freeze([
+export const getGeneratedSiteRoutes = ({ searchEnabled = false } = {}) => Object.freeze([
 	Object.freeze({
 		kind: 'generated-route',
 		label: `Norna generated ${sitemapFilename}`,
 		pathname: `/${sitemapFilename}`,
 	}),
+	...(searchEnabled ? [Object.freeze({
+		kind: 'generated-route',
+		label: 'Norna generated search page',
+		pathname: '/search/',
+	})] : []),
 ]);
 
+export const generatedSiteRoutes = getGeneratedSiteRoutes();
+
 const getPagePathname = (page) => page.pathname ?? getSiteNodePathname(page.contentFile ?? page);
 const getPageLabel = (page) => page.contentLabel ?? page.contentFile?.contentLabel ?? page.entry?.id ?? getPagePathname(page);
 const getPageAliases = (page) => page.aliases ?? page.data?.page?.aliases ?? [];
@@ -99,6 +106,19 @@ export const createPageAliasModel = ({
 		for (const identity of getPublicFileIdentities(file)) addIdentity(identity);
 	}
 	for (const route of generatedRoutes) {
+		const conflict = identitiesByPathname.get(route.pathname);
+		if (conflict) {
+			diagnostics.push({
+				code: 'generated-route-collision',
+				contentFile: conflict.kind === 'page'
+					? conflict.source.contentFile ?? conflict.source
+					: undefined,
+				fix: `Move or rename the conflicting source. ${route.label} owns ${route.pathname} while the feature is enabled.`,
+				message: `Generated route "${route.pathname}" from ${route.label} conflicts with ${describeIdentity(conflict)}.`,
+				severity: 'error',
+			});
+			continue;
+		}
 		addIdentity(createIdentity({ ...route, source: route }));
 	}
 

package/scripts/lib/page-markdown.mjs

@@ -1,3 +1,4 @@
+import { getCodeFenceMetadataDiagnostics } from './code-fence-metadata.mjs';
 import {
 	getHeadingIdentifierIssues,
 	getMarkdownHeadings,
@@ -11,7 +12,9 @@ import {
 	extractMarkdownImageReferences,
 	extractNornaMarkdownBlockDiagnostics,
 	getNornaBlockImageReferences,
+	nornaBlockTypes,
 } from './norna-markdown-blocks.mjs';
+import { getSemanticCalloutDiagnostics } from './semantic-callouts.mjs';
 
 const normalizeMarkdownWithOffsets = (source) => {
 	const input = String(source);
@@ -172,7 +175,7 @@ const getRegionContent = (regionMarkdown, blocks, regionOffset) => {
 	return content.filter((item) => item.kind !== 'markdown' || item.markdown.length > 0);
 };
 
-const createRegion = ({ heading, nextHeading, headings, source, label, lineOffset }) => {
+const createRegion = ({ calloutErrors, codeFenceErrors, heading, nextHeading, headings, source, label, lineOffset }) => {
 	const endOffset = nextHeading?.index ?? source.length;
 	const markdown = source.slice(heading.index, endOffset).trimEnd();
 	const regionLineOffset = lineOffset + heading.line - 1;
@@ -197,6 +200,8 @@ const createRegion = ({ heading, nextHeading, headings, source, label, lineOffse
 		bodyMarkdown: source.slice(heading.index + heading.source.length, endOffset).trimEnd(),
 		blocks: blockResult.blocks,
 		blockErrors: blockResult.errors,
+		calloutErrors: calloutErrors.filter((error) => error.offset >= heading.index && error.offset < endOffset),
+		codeFenceErrors: codeFenceErrors.filter((error) => error.offset >= heading.index && error.offset < endOffset),
 		content: getRegionContent(markdown, blockResult.blocks, heading.index),
 		endOffset,
 		heading,
@@ -220,12 +225,20 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	const label = options.label ?? 'Markdown';
 	const lineOffset = options.lineOffset ?? 0;
 	const { headings, tree } = await getMarkdownHeadings(source);
+	const calloutErrors = getSemanticCalloutDiagnostics(tree, { label, lineOffset });
+	const codeFenceErrors = getCodeFenceMetadataDiagnostics(tree, {
+		excludedLanguages: nornaBlockTypes,
+		label,
+		lineOffset,
+	});
 	const structuralHeadings = headings.filter((heading) => heading.depth <= 2);
 	const prelude = structuralHeadings.length > 0
 		? source.slice(0, structuralHeadings[0].index)
 		: source;
 	const pageHeadings = structuralHeadings.filter((heading) => heading.depth === 1);
 	const regions = structuralHeadings.map((heading, index) => createRegion({
+		calloutErrors,
+		codeFenceErrors,
 		heading,
 		nextHeading: structuralHeadings[index + 1],
 		headings,
@@ -250,6 +263,22 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		regionId: region.id,
 		severity: 'error',
 	})));
+	const calloutDiagnostics = regions.flatMap((region) => region.calloutErrors.map((error) => ({
+		code: error.code,
+		fix: error.fix,
+		line: error.line,
+		message: error.message,
+		regionId: region.id,
+		severity: 'error',
+	})));
+	const codeFenceDiagnostics = regions.flatMap((region) => region.codeFenceErrors.map((error) => ({
+		code: error.code,
+		fix: error.fix,
+		line: error.line,
+		message: error.message,
+		regionId: region.id,
+		severity: 'error',
+	})));
 	const blocks = regions.flatMap((region) => region.blocks);
 	const links = [
 		...extractMarkdownLinks({ source, tree, lineOffset }),
@@ -279,6 +308,8 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 			...headingDiagnostics,
 			...blockDiagnostics,
 			...noteDiagnostics,
+			...calloutDiagnostics,
+			...codeFenceDiagnostics,
 		],
 		headings,
 		headingIssues,