@janga/norna 0.7.16 → 0.7.17

package/scripts/lib/editor-language-service.mjs

@@ -9,12 +9,11 @@ import {
 	nornaMarkdownBlockDefinitions,
 } from './norna-markdown-blocks.mjs';
 import { inspectPublicAssetFilenames, logoAssetFilenames } from './public-asset-conventions.mjs';
+import { getHeadingIdentifierIssues, getMarkdownHeadings } from './heading-ids.mjs';
 import { siteSchema } from './schema-definitions.mjs';
 
 const supportedImageExtensions = new Set(['.jpg', '.jpeg', '.png', '.svg']);
 const siteConfigNames = ['config.yaml'];
-const headingIdPattern = /^##\s+.+?\s*\{#([a-z0-9-]+)\}\s*$/;
-
 const fileExists = (filePath) => access(filePath).then(() => true, () => false);
 const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
@@ -37,7 +36,7 @@ export const findNornaSiteRoot = async (documentPath) => {
 	}
 };
 
-const readSitewideNavigationForEditor = async (siteRoot) => {
+const readSitewideLogoForEditor = async (siteRoot) => {
 	const filename = await findFile(siteRoot, ['sitewide-content.yaml']);
 	if (!filename) return null;
 	const absolutePath = path.join(siteRoot, filename);
@@ -45,15 +44,16 @@ const readSitewideNavigationForEditor = async (siteRoot) => {
 
 	try {
 		const data = load(source) ?? {};
-		const navigation = data && typeof data === 'object' && data.navigation && typeof data.navigation === 'object'
-			? data.navigation
-			: {};
+		const logoConfigured = Boolean(
+			data
+			&& typeof data === 'object'
+			&& Object.hasOwn(data, 'logo'),
+		);
 		const logoLine = source.replace(/\r\n?/g, '\n').split('\n')
-			.findIndex((line) => /^\s+logo:\s*(?:#.*)?$/.test(line)) + 1;
+			.findIndex((line) => /^logo:\s*(?:#.*)?$/.test(line)) + 1;
 		return {
 			absolutePath,
-			label: typeof navigation.label === 'string' ? navigation.label : null,
-			logoConfigured: Object.hasOwn(navigation, 'logo'),
+			logoConfigured,
 			logoLine: logoLine > 0 ? logoLine : 1,
 		};
 	} catch {
@@ -73,7 +73,7 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 	const inspection = inspectPublicAssetFilenames(
 		entries.filter((entry) => entry.isFile()).map((entry) => entry.name),
 	);
-	const navigation = await readSitewideNavigationForEditor(siteRoot);
+	const sitewideLogo = await readSitewideLogoForEditor(siteRoot);
 	const issues = inspection.suspicious.map((issue) => ({
 		...issue,
 		absolutePath: path.join(publicDirectory, issue.filename),
@@ -92,14 +92,14 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 			});
 		}
 	}
-	if (inspection.logos.length === 0 && navigation?.logoConfigured) {
+	if (inspection.logos.length === 0 && sitewideLogo?.logoConfigured) {
 		const publicLabel = toPosixPath(path.relative(path.dirname(siteRoot), publicDirectory));
 		issues.push({
-			absolutePath: navigation.absolutePath,
+			absolutePath: sitewideLogo.absolutePath,
 			code: 'missing-logo-file',
-			filename: path.basename(navigation.absolutePath),
-			line: navigation.logoLine,
-			message: `Navigation logo settings are configured, but no logo file was found. Add exactly one of ${logoAssetFilenames.map((filename) => `${publicLabel}/${filename}`).join(', ')}, or remove navigation.logo.`,
+			filename: path.basename(sitewideLogo.absolutePath),
+			line: sitewideLogo.logoLine,
+			message: `Logo display settings are configured, but no logo file was found. Add exactly one of ${logoAssetFilenames.map((filename) => `${publicLabel}/${filename}`).join(', ')}, or remove logo.`,
 			severity: 'error',
 		});
 	}
@@ -107,7 +107,7 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 	return {
 		...inspection,
 		issues,
-		navigation,
+		sitewideLogo,
 		publicDirectory,
 		siteRoot,
 	};
@@ -121,34 +121,22 @@ const getPageContext = (siteRoot, documentPath) => {
 			contentPath: absoluteDocumentPath,
 			imagesRoot: path.join(siteRoot, 'images'),
 			pageLabel: 'Home',
-			routeDirectory: null,
+			pageDirectory: null,
 		};
 	}
 
-	const match = relativePath.match(/^routes\/(.+)\/content\.md$/);
+	const match = relativePath.match(/^pages\/(.+)\/content\.md$/);
 	if (!match) return null;
 
-	const routeDirectory = match[1];
+	const pageDirectory = match[1];
 	return {
 		contentPath: absoluteDocumentPath,
-		imagesRoot: path.join(siteRoot, 'routes', ...routeDirectory.split('/'), 'images'),
-		pageLabel: routeDirectory,
-		routeDirectory,
+		imagesRoot: path.join(siteRoot, 'pages', ...pageDirectory.split('/'), 'images'),
+		pageLabel: pageDirectory,
+		pageDirectory,
 	};
 };
 
-const getSectionAtLine = (source, lineIndex) => {
-	const lines = source.replace(/\r\n?/g, '\n').split('\n');
-	let section = null;
-
-	for (let index = 0; index <= Math.min(lineIndex, lines.length - 1); index += 1) {
-		const match = lines[index].match(headingIdPattern);
-		if (match) section = { id: match[1], line: index };
-	}
-
-	return section;
-};
-
 const getOpenFenceAtLine = (source, lineIndex) => {
 	const lines = source.replace(/\r\n?/g, '\n').split('\n');
 	let open = null;
@@ -304,12 +292,11 @@ const collectImageFiles = async (directory, imageRoot, pageLabel, files) => {
 			filename: entry.name,
 			pageLabel,
 			relativeToImages,
-			sectionId: relativeToImages.split('/')[0] ?? '',
 		});
 	}
 };
 
-const collectRouteImageRoots = async (directory, siteRoot, roots) => {
+const collectPageImageRoots = async (directory, siteRoot, roots) => {
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') return [];
 		throw error;
@@ -319,11 +306,11 @@ const collectRouteImageRoots = async (directory, siteRoot, roots) => {
 		if (!entry.isDirectory()) continue;
 		const absolutePath = path.join(directory, entry.name);
 		if (entry.name === 'images') {
-			const routeDirectory = toPosixPath(path.relative(path.join(siteRoot, 'routes'), path.dirname(absolutePath)));
-			roots.push({ imageRoot: absolutePath, pageLabel: routeDirectory });
+			const pageDirectory = toPosixPath(path.relative(path.join(siteRoot, 'pages'), path.dirname(absolutePath)));
+			roots.push({ imageRoot: absolutePath, pageLabel: pageDirectory });
 			continue;
 		}
-		await collectRouteImageRoots(absolutePath, siteRoot, roots);
+		await collectPageImageRoots(absolutePath, siteRoot, roots);
 	}
 };
 
@@ -344,7 +331,7 @@ const getContentFiles = async (siteRoot) => {
 		}
 	};
 
-	await visit(path.join(siteRoot, 'routes'));
+	await visit(path.join(siteRoot, 'pages'));
 	return files;
 };
 
@@ -366,9 +353,9 @@ export const createSiteImageIndex = async (siteRoot) => {
 	const homeImageRoot = path.join(siteRoot, 'images');
 	await collectImageFiles(homeImageRoot, homeImageRoot, 'Home', files);
 
-	const routeRoots = [];
-	await collectRouteImageRoots(path.join(siteRoot, 'routes'), siteRoot, routeRoots);
-	for (const root of routeRoots) {
+	const pageRoots = [];
+	await collectPageImageRoots(path.join(siteRoot, 'pages'), siteRoot, pageRoots);
+	for (const root of pageRoots) {
 		await collectImageFiles(root.imageRoot, root.imageRoot, root.pageLabel, files);
 	}
 
@@ -397,9 +384,7 @@ export const getImageCompletionContext = async ({ documentPath, source, line })
 	const currentLine = source.replace(/\r\n?/g, '\n').split('\n')[line] ?? '';
 	if (!/^\s*(?:-\s+)?image:\s*[^\s]*$/.test(currentLine)) return null;
 
-	const section = getSectionAtLine(source, line);
-	if (!section) return null;
-	const expectedDirectory = path.join(page.imagesRoot, section.id);
+	const expectedDirectory = page.imagesRoot;
 	const index = await createSiteImageIndex(siteRoot);
 	const candidates = index.files.map((file) => {
 		const isExpected = path.dirname(file.absolutePath) === expectedDirectory;
@@ -421,7 +406,6 @@ export const getImageCompletionContext = async ({ documentPath, source, line })
 		candidates,
 		expectedDirectory,
 		page,
-		section,
 		siteRoot,
 	};
 };
@@ -434,10 +418,9 @@ export const getImageDefinitionContext = async ({ documentPath, source, line })
 	const filename = match[1].replace(/^['"]|['"]$/g, '');
 	const siteRoot = await findNornaSiteRoot(documentPath);
 	const page = siteRoot ? getPageContext(siteRoot, documentPath) : null;
-	const section = getSectionAtLine(source, line);
-	if (!siteRoot || !page || !section) return null;
+	if (!siteRoot || !page) return null;
 
-	const expectedPath = path.join(page.imagesRoot, section.id, filename);
+	const expectedPath = path.join(page.imagesRoot, filename);
 	if (await fileExists(expectedPath)) return { files: [expectedPath], filename, siteRoot };
 
 	const index = await createSiteImageIndex(siteRoot);
@@ -480,7 +463,9 @@ const getImageReferenceLines = (source) => {
 const getContentFrontmatterDiagnostics = (source) => {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
 	if (!match) {
-		return [{ severity: 'error', line: 1, message: 'Norna content files must start with YAML frontmatter delimited by ---.' }];
+		return /^---(?:\r?\n|$)/.test(source)
+			? [{ severity: 'error', line: 1, message: 'YAML frontmatter starts with ---, but no closing --- delimiter was found.' }]
+			: [];
 	}
 
 	let data;
@@ -504,21 +489,98 @@ const getContentFrontmatterDiagnostics = (source) => {
 	}));
 };
 
-const getSectionHeadingDiagnostics = (source) => source.replace(/\r\n?/g, '\n').split('\n')
-	.flatMap((line, index) => {
-		if (!/^##(?:\s|$)/.test(line) || headingIdPattern.test(line)) return [];
-		return [{
-			code: 'missing-section-id',
+const getMarkdownStructure = (source) => {
+	const lines = source.replace(/\r\n?/g, '\n').split('\n');
+	let bodyStart = 0;
+	if (lines[0]?.trim() === '---') {
+		const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+		if (closingIndex < 0) return { bodyStart: lines.length, headings: [], lines };
+		bodyStart = closingIndex + 1;
+	}
+
+	const headings = [];
+	let fence = null;
+	for (let index = bodyStart; index < lines.length; index += 1) {
+		const line = lines[index];
+		const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})([^\r\n]*)$/);
+		if (fenceMatch) {
+			if (!fence) {
+				fence = { character: fenceMatch[1][0], length: fenceMatch[1].length };
+			} else if (
+				fenceMatch[1][0] === fence.character
+				&& fenceMatch[1].length >= fence.length
+				&& !fenceMatch[2].trim()
+			) {
+				fence = null;
+			}
+			continue;
+		}
+		if (fence) continue;
+
+		const match = line.match(/^(#{1,2})\s+(.+?)\s*$/);
+		if (match) headings.push({ level: match[1].length, line: index + 1, source: line });
+	}
+
+	return { bodyStart, headings, lines };
+};
+
+const getPageTitleDiagnostics = (structure) => {
+	const { bodyStart, headings, lines } = structure;
+	const pageHeadings = headings.filter((heading) => heading.level === 1);
+	const diagnostics = [];
+
+	if (pageHeadings.length === 0) {
+		diagnostics.push({
+			code: 'missing-page-title',
 			severity: 'error',
-			line: index + 1,
-			message: 'Level 2 Norna section headings require an explicit id, for example "## Introduction {#introduction}".',
-		}];
-	});
+			line: 1,
+			message: 'Norna pages require exactly one Markdown H1 page title, for example "# About".',
+		});
+	} else if (pageHeadings.length > 1) {
+		for (const heading of pageHeadings.slice(1)) {
+			diagnostics.push({
+				code: 'duplicate-page-title',
+				severity: 'error',
+				line: heading.line,
+				message: 'A Norna page can contain only one Markdown H1. Use a level 2 heading with an explicit id for a section.',
+			});
+		}
+	}
+
+	if (headings[0] && headings[0].level !== 1) {
+		diagnostics.push({
+			code: 'page-title-order',
+			severity: 'error',
+			line: headings[0].line,
+			message: 'The Markdown H1 page title must come before every level 2 section.',
+		});
+	}
+
+	const firstHeadingLineIndex = (headings[0]?.line ?? lines.length + 1) - 1;
+	if (lines.slice(bodyStart, firstHeadingLineIndex).some((line) => line.trim())) {
+		diagnostics.push({
+			code: 'page-title-order',
+			severity: 'error',
+			line: bodyStart + 1,
+			message: 'The Markdown H1 page title must be the first content after optional frontmatter.',
+		});
+	}
+
+	return diagnostics;
+};
 
 export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
+	const markdownStructure = getMarkdownStructure(source);
+	const { headings } = await getMarkdownHeadings(source);
 	const diagnostics = [
 		...getContentFrontmatterDiagnostics(source),
-		...getSectionHeadingDiagnostics(source),
+		...getPageTitleDiagnostics(markdownStructure),
+		...getHeadingIdentifierIssues(headings).map((issue) => ({
+			code: issue.code,
+			severity: 'error',
+			line: issue.heading.line,
+			message: `${issue.message} ${issue.fix}`,
+		})),
 	];
 	const blockResult = extractNornaMarkdownBlockDiagnostics(source, { label: path.basename(documentPath) });
 	for (const error of blockResult.errors) {
@@ -547,9 +609,7 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 
 	const index = await createSiteImageIndex(siteRoot);
 	for (const reference of getImageReferenceLines(source)) {
-		const section = getSectionAtLine(source, reference.line - 1);
-		if (!section) continue;
-		const expectedPath = path.join(page.imagesRoot, section.id, reference.filename);
+		const expectedPath = path.join(page.imagesRoot, reference.filename);
 		if (await fileExists(expectedPath)) continue;
 
 		const candidates = index.filesByName.get(reference.filename) ?? [];
@@ -558,7 +618,7 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 				code: 'missing-image',
 				severity: 'error',
 				line: reference.line,
-				message: `Image "${reference.filename}" was not found in the expected section folder or elsewhere in this Norna site.`,
+				message: `Image "${reference.filename}" was not found in this page's images folder or elsewhere in this Norna site.`,
 			});
 			continue;
 		}
@@ -586,7 +646,7 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 			line: reference.line,
 			message: otherReferences.length > 0
 				? `Image "${reference.filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))} and is still referenced by ${otherReferences.join(', ')}. Norna cannot relocate it safely.`
-				: `Image "${reference.filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))}. Run "norna content:sync" to relocate it to this section.`,
+				: `Image "${reference.filename}" is stored at ${toPosixPath(path.relative(siteRoot, candidate.absolutePath))}. Run "norna content:sync" to relocate it to this page's images folder.`,
 		});
 	}
 

package/scripts/lib/heading-ids.mjs

@@ -0,0 +1,161 @@
+import { markdownToMdast } from 'satteri';
+
+export const explicitHeadingIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const reservedHeadingIds = new Set(['page-title']);
+
+const explicitHeadingIdSuffixPattern = /\s*\{#([^{}]*)\}\s*$/;
+const transliterations = new Map([
+	['æ', 'ae'],
+	['đ', 'd'],
+	['ð', 'd'],
+	['ħ', 'h'],
+	['ı', 'i'],
+	['ł', 'l'],
+	['ø', 'o'],
+	['œ', 'oe'],
+	['ß', 'ss'],
+	['þ', 'th'],
+]);
+
+const transliterateToAscii = (value) => Array.from(value)
+	.map((character) => transliterations.get(character) ?? character)
+	.join('');
+
+export const slugifyHeadingText = (value) => transliterateToAscii(value
+	.normalize('NFKD')
+	.toLowerCase())
+	.replace(/\p{Mark}+/gu, '')
+	.replace(/['’]/g, '')
+	.replace(/[^a-z0-9]+/g, '-')
+	.replace(/^-+|-+$/g, '');
+
+const getNodeText = (node) => {
+	if (!node || typeof node !== 'object') return '';
+	if (node.type === 'text' || node.type === 'inlineCode') return node.value ?? '';
+	if (node.type === 'image') return node.alt ?? '';
+	if (!Array.isArray(node.children)) return '';
+	return node.children.map(getNodeText).join('');
+};
+
+export const resolveHeadingIdentifier = (headingText, depth) => {
+	const explicitMatch = headingText.match(explicitHeadingIdSuffixPattern);
+	const explicitSource = explicitMatch?.[1];
+	const title = explicitMatch
+		? headingText.slice(0, explicitMatch.index).trim()
+		: headingText.trim();
+	const explicitId = explicitSource && explicitHeadingIdPattern.test(explicitSource)
+		? explicitSource
+		: null;
+
+	return {
+		depth,
+		explicitId,
+		explicitSource: explicitSource ?? null,
+		id: depth === 1 ? null : explicitId ?? slugifyHeadingText(title),
+		title,
+	};
+};
+
+export const getMarkdownHeadings = async (source) => {
+	const normalizedSource = source.replace(/\r\n?/g, '\n');
+	const tree = await markdownToMdast(normalizedSource, {
+		features: {
+			frontmatter: true,
+			gfm: true,
+		},
+	});
+
+	const headings = tree.children
+		.filter((node) => node.type === 'heading' && node.depth >= 1 && node.depth <= 3)
+		.map((node) => ({
+			...resolveHeadingIdentifier(getNodeText(node), node.depth),
+			index: node.position?.start.offset ?? 0,
+			line: node.position?.start.line ?? 1,
+			source: normalizedSource.slice(
+				node.position?.start.offset ?? 0,
+				node.position?.end.offset ?? node.position?.start.offset ?? 0,
+			),
+		}));
+
+	return { headings, source: normalizedSource };
+};
+
+export const getHeadingIdentifierIssues = (headings) => {
+	const issues = [];
+	const headingsById = new Map();
+
+	for (const heading of headings) {
+		if (heading.depth === 1) {
+			if (heading.explicitSource !== null) {
+				issues.push({
+					code: 'page-title-id',
+					heading,
+					message: 'The Markdown H1 is the page title and must not have an id.',
+					fix: 'Remove the {#...} suffix. Heading ids apply to H2 and H3.',
+				});
+			}
+			continue;
+		}
+
+		if (heading.explicitSource !== null && !heading.explicitId) {
+			issues.push({
+				code: 'invalid-heading-id',
+				heading,
+				message: `Heading "${heading.title}" has an invalid explicit id "${heading.explicitSource}".`,
+				fix: 'Use lowercase ASCII letters, numbers, and single hyphens, for example {#getting-started}.',
+			});
+			continue;
+		}
+
+		if (!heading.id) {
+			issues.push({
+				code: 'empty-heading-id',
+				heading,
+				message: `Heading "${heading.title}" cannot produce an automatic ASCII id.`,
+				fix: `Add an explicit id, for example ${'#'.repeat(heading.depth)} ${heading.title} {#section-id}.`,
+			});
+			continue;
+		}
+
+		if (reservedHeadingIds.has(heading.id)) {
+			issues.push({
+				code: 'reserved-heading-id',
+				heading,
+				message: `Heading id "${heading.id}" is reserved by Norna.`,
+				fix: 'Choose another explicit id.',
+			});
+			continue;
+		}
+
+		const existing = headingsById.get(heading.id);
+		if (existing) {
+			issues.push({
+				code: 'duplicate-heading-id',
+				heading,
+				otherHeading: existing,
+				message: `Two headings resolve to id "${heading.id}".`,
+				fix: `Add a unique explicit id to at least one heading, for example {#${heading.id}-details}.`,
+			});
+			continue;
+		}
+
+		headingsById.set(heading.id, heading);
+	}
+
+	return issues;
+};
+
+export const formatHeadingIdentifierIssue = (issue, sourceLabel = 'Markdown') => {
+	const lines = [`${sourceLabel}: ${issue.message}`];
+	if (issue.otherHeading) {
+		lines.push(
+			`- line ${issue.otherHeading.line}: "${issue.otherHeading.title}"`,
+			`- line ${issue.heading.line}: "${issue.heading.title}"`,
+		);
+	} else {
+		lines.push(`- line ${issue.heading.line}: "${issue.heading.title}"`);
+	}
+	if (issue.fix) lines.push(issue.fix);
+
+	return lines.join('\n');
+};

package/scripts/lib/navigation-model.mjs

@@ -0,0 +1,51 @@
+export const navigationModeNames = Object.freeze([
+	'automatic',
+	'sections',
+	'top',
+	'tree',
+]);
+
+const assertNavigationMode = (mode) => {
+	if (!navigationModeNames.includes(mode)) {
+		throw new Error(`Unknown navigation mode "${mode}". Use one of: ${navigationModeNames.join(', ')}.`);
+	}
+
+	return mode;
+};
+
+const getListedPages = (pages) => pages.filter((page) => page.isHome || page.listed !== false);
+
+const getPageNavigationDepth = (page) => {
+	const pageDepth = page.depth ?? 1;
+	return (page.headings ?? []).reduce((maximum, heading) => (
+		Math.max(maximum, pageDepth + heading.depth - 1)
+	), pageDepth);
+};
+
+export const getAutomaticNavigationMode = (pages) => {
+	const listedPages = getListedPages(pages);
+	if (listedPages.length <= 1) return 'sections';
+
+	const maximumDepth = listedPages.reduce((maximum, page) => (
+		Math.max(maximum, getPageNavigationDepth(page))
+	), 1);
+
+	return maximumDepth <= 2 ? 'top' : 'tree';
+};
+
+export const resolveNavigationModel = ({ mode = 'automatic', pages }) => {
+	const requestedMode = assertNavigationMode(mode);
+	const listedPages = getListedPages(pages);
+	const maximumDepth = listedPages.reduce((maximum, page) => (
+		Math.max(maximum, getPageNavigationDepth(page))
+	), 1);
+
+	return Object.freeze({
+		mode: requestedMode === 'automatic'
+			? getAutomaticNavigationMode(listedPages)
+			: requestedMode,
+		requestedMode,
+		listedPageCount: listedPages.length,
+		maximumDepth,
+	});
+};

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

@@ -3,12 +3,11 @@ import { documentationLink } from './documentation-links.mjs';
 
 const field = (description, options = {}) => Object.freeze({ description, ...options });
 const value = (title, description) => Object.freeze({ title, description });
-const nornaBlocksDocumentation = documentationLink('Norna blocks reference', 'content.md', 'norna-blocks');
 
 export const nornaMarkdownBlockDefinitions = Object.freeze({
 	'norna-image-stack': Object.freeze({
 		description: 'Display one or more managed images in a vertical stack.',
-		documentation: nornaBlocksDocumentation,
+		documentation: documentationLink('Image stack reference', 'content.md', 'image-stack'),
 		item: Object.freeze({
 			start: field('Start another managed image.', { key: 'image', prefix: '- ' }),
 			fields: Object.freeze({
@@ -19,7 +18,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 	}),
 	'norna-image-carousel': Object.freeze({
 		description: 'Display two or more managed images in an interactive carousel.',
-		documentation: nornaBlocksDocumentation,
+		documentation: documentationLink('Image carousel reference', 'content.md', 'image-carousel'),
 		item: Object.freeze({
 			start: field('Start another managed carousel image.', { key: 'image', prefix: '- ' }),
 			fields: Object.freeze({
@@ -30,7 +29,7 @@ export const nornaMarkdownBlockDefinitions = Object.freeze({
 	}),
 	'norna-card-list': Object.freeze({
 		description: 'Display a structured list of cards.',
-		documentation: nornaBlocksDocumentation,
+		documentation: documentationLink('Card list reference', 'content.md', 'card-list'),
 		options: Object.freeze({
 			layout: field('Place each card image above, left, or right of its text. Defaults to image-top.', {
 				default: 'image-top',

package/scripts/lib/page-model.mjs

@@ -0,0 +1,83 @@
+export const pageDirectoryPattern = /^(?!000)(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+const pageEntryPathSeparator = '--';
+
+export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
+	const match = pageDirectory.match(pageDirectoryPattern);
+
+	if (!match) {
+		throw new Error(
+			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. The prefix must be 001-999 and page-id may contain only lowercase letters, numbers, and single hyphens.`,
+		);
+	}
+
+	return {
+		pageDirectory,
+		pageOrder: Number.parseInt(match[1], 10),
+		pageId: match[2],
+	};
+};
+
+const normalizePageDirectoryPath = (pageDirectoryPath) => pageDirectoryPath.replaceAll('\\', '/');
+
+export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page directory path') => {
+	const normalizedPath = normalizePageDirectoryPath(pageDirectoryPath);
+	const segments = normalizedPath.split('/').filter(Boolean);
+
+	if (!normalizedPath || normalizedPath.startsWith('/') || normalizedPath.endsWith('/') || segments.length % 2 === 0) {
+		throw new Error(
+			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form NNN-page-id/pages/NNN-child-id.`,
+		);
+	}
+
+	const pageDirectories = [];
+	for (const [index, segment] of segments.entries()) {
+		if (index % 2 === 1) {
+			if (segment !== 'pages') {
+				throw new Error(
+					`Invalid ${label} "${pageDirectoryPath}". Use a pages directory between nested page directories.`,
+				);
+			}
+			continue;
+		}
+
+		pageDirectories.push(parsePageDirectory(segment, `${label} segment ${segment}`));
+	}
+
+	const pageIds = pageDirectories.map(({ pageId }) => pageId);
+	const pageOrders = pageDirectories.map(({ pageOrder }) => pageOrder);
+	const currentPage = pageDirectories.at(-1);
+
+	return {
+		pageDirectory: normalizedPath,
+		pageDirectories: pageDirectories.map(({ pageDirectory }) => pageDirectory),
+		pageId: currentPage.pageId,
+		pageIds,
+		pageOrder: currentPage.pageOrder,
+		pageOrders,
+		pagePath: pageIds.join('/'),
+		parentPagePath: pageIds.length > 1 ? pageIds.slice(0, -1).join('/') : null,
+		depth: pageIds.length,
+	};
+};
+
+export const encodePageDirectoryPath = (pageDirectoryPath) => {
+	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
+	return pageDirectories.join(pageEntryPathSeparator);
+};
+
+export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path') => {
+	const pageDirectories = pageEntryPath.split(pageEntryPathSeparator);
+	if (pageDirectories.some((pageDirectory) => !pageDirectory)) {
+		throw new Error(`Invalid ${label} "${pageEntryPath}".`);
+	}
+
+	return pageDirectories.join('/pages/');
+};
+
+export const getPageDirectoryAncestors = (pageDirectoryPath) => {
+	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
+	return pageDirectories.map((_, index) => (
+		pageDirectories.slice(0, index + 1).join('/pages/')
+	));
+};