@janga/norna 0.7.23 → 0.7.25

package/src/components/TreeNavigationScript.astro

@@ -1,39 +1,109 @@
 <script>
 	type NavigationState = {
 		openPaths: string[];
-		sectionPaths: string[];
+		sectionOpenByPath: Record<string, boolean>;
+		scrollTop: number;
+	};
+	type SharedNavigationState = Pick<NavigationState, 'openPaths' | 'sectionOpenByPath'>;
+	type NavigationSnapshot = {
+		branchOpen: boolean[];
+		sectionOpen: boolean[];
 		scrollTop: number;
 	};
 
 	const setupNavigationState = (container: HTMLElement, scope: 'desktop' | 'mobile') => {
 		const root = container.dataset.navigationRoot ?? '/';
+		const sharedRoot = container.dataset.navigationStateRoot ?? root;
 		const stateKey = `norna:tree-navigation:${scope}:${root}`;
+		const sharedStateKey = `norna:tree-navigation:shared:${sharedRoot}`;
 		const branches = Array.from(container.querySelectorAll<HTMLDetailsElement>(
 			'.navigation-page-disclosure[data-page-path]',
 		));
-		let storedState: NavigationState = { openPaths: [], sectionPaths: [], scrollTop: 0 };
+		const sectionBranches = Array.from(container.querySelectorAll<HTMLDetailsElement>(
+			'.navigation-page-sections-disclosure[data-page-path]',
+		));
+		const navigationNodes = Array.from(container.querySelectorAll<HTMLElement>(
+			'.navigation-page-node[data-navigation-title]',
+		));
+		const getScrollContainer = () => {
+			let candidate: HTMLElement | null = container;
 
-		try {
-			const parsedState = JSON.parse(sessionStorage.getItem(stateKey) ?? '{}');
-			storedState = {
-				openPaths: Array.isArray(parsedState.openPaths) ? parsedState.openPaths : [],
-				sectionPaths: Array.isArray(parsedState.sectionPaths) ? parsedState.sectionPaths : [],
-				scrollTop: Number.isFinite(Number(parsedState.scrollTop)) ? Number(parsedState.scrollTop) : 0,
-			};
+			while (candidate) {
+				if (/auto|scroll/.test(getComputedStyle(candidate).overflowY)) return candidate;
+				candidate = candidate.parentElement;
+			}
 
+			return container;
+		};
+		const scrollContainer = getScrollContainer();
+		let filterSnapshot: NavigationSnapshot | null = null;
+		let lastSharedState = '';
+		const parseState = (value: string | null): NavigationState => {
+			try {
+				const parsedState = JSON.parse(value ?? '{}');
+				return {
+					openPaths: Array.isArray(parsedState.openPaths) ? parsedState.openPaths : [],
+					sectionOpenByPath: parsedState.sectionOpenByPath
+						&& typeof parsedState.sectionOpenByPath === 'object'
+						? Object.fromEntries(Object.entries(parsedState.sectionOpenByPath)
+							.filter((entry): entry is [string, boolean] => typeof entry[1] === 'boolean'))
+						: {},
+					scrollTop: Number.isFinite(Number(parsedState.scrollTop)) ? Number(parsedState.scrollTop) : 0,
+				};
+			} catch {
+				return { openPaths: [], sectionOpenByPath: {}, scrollTop: 0 };
+			}
+		};
+		const getDisclosureState = (): SharedNavigationState => ({
+			openPaths: branches.filter((branch) => branch.open)
+				.map((branch) => branch.dataset.pagePath ?? ''),
+			sectionOpenByPath: Object.fromEntries(sectionBranches.map((branch) => [
+				branch.dataset.pagePath ?? '',
+				branch.open,
+			])),
+		});
+		const applyDisclosureState = (state: SharedNavigationState) => {
 			branches.forEach((branch) => {
 				const pagePath = branch.dataset.pagePath ?? '';
 				branch.open = branch.dataset.currentBranch === 'true'
-					|| storedState.openPaths.includes(pagePath);
-
-				if (storedState.sectionPaths.includes(pagePath)) {
-					branch.dataset.sectionsOpen = 'true';
-				}
+					|| state.openPaths.includes(pagePath);
+			});
+			sectionBranches.forEach((branch) => {
+				const pagePath = branch.dataset.pagePath ?? '';
+				const storedOpen = state.sectionOpenByPath[pagePath];
+				branch.open = typeof storedOpen === 'boolean'
+					? storedOpen
+					: branch.dataset.currentPage === 'true';
 			});
+		};
+		const mergeSharedState = (state: SharedNavigationState): SharedNavigationState => {
+			const existingState = parseState(sessionStorage.getItem(sharedStateKey));
+			const knownBranchPaths = new Set(branches.map((branch) => branch.dataset.pagePath ?? ''));
+			return {
+				openPaths: [
+					...existingState.openPaths.filter((pagePath) => !knownBranchPaths.has(pagePath)),
+					...state.openPaths,
+				],
+				sectionOpenByPath: {
+					...existingState.sectionOpenByPath,
+					...state.sectionOpenByPath,
+				},
+			};
+		};
+
+		try {
+			const storedState = parseState(sessionStorage.getItem(stateKey));
+			const storedSharedState = sessionStorage.getItem(sharedStateKey);
+			applyDisclosureState(storedSharedState === null
+				? storedState
+				: parseState(storedSharedState));
+			const initialSharedState = mergeSharedState(getDisclosureState());
+			lastSharedState = JSON.stringify(initialSharedState);
+			sessionStorage.setItem(sharedStateKey, lastSharedState);
 
 			if (storedState.scrollTop > 0) {
 				requestAnimationFrame(() => {
-					container.scrollTop = storedState.scrollTop;
+					scrollContainer.scrollTop = storedState.scrollTop;
 				});
 			}
 		} catch {
@@ -41,37 +111,204 @@
 		}
 
 		const saveState = () => {
+			if (filterSnapshot) return;
+
 			try {
-				const openBranches = branches.filter((branch) => branch.open);
+				const disclosureState = getDisclosureState();
 				const state: NavigationState = {
-					openPaths: openBranches.map((branch) => branch.dataset.pagePath ?? ''),
-					sectionPaths: openBranches
-						.filter((branch) => (
-							branch.dataset.sectionsOpen === 'true'
-							|| branch.dataset.currentPage === 'true'
-						))
-						.map((branch) => branch.dataset.pagePath ?? ''),
-					scrollTop: container.scrollTop,
+					...disclosureState,
+					scrollTop: scrollContainer.scrollTop,
 				};
 				sessionStorage.setItem(stateKey, JSON.stringify(state));
+				const sharedState = mergeSharedState(disclosureState);
+				const serializedSharedState = JSON.stringify(sharedState);
+				sessionStorage.setItem(sharedStateKey, serializedSharedState);
+				if (serializedSharedState !== lastSharedState) {
+					lastSharedState = serializedSharedState;
+					window.dispatchEvent(new CustomEvent('norna:tree-navigation-state', {
+						detail: { root: sharedRoot, state: sharedState },
+					}));
+				}
 			} catch {
 				// Navigation state persistence is an optional enhancement.
 			}
 		};
+		window.addEventListener('norna:tree-navigation-state', (event) => {
+			const detail = (event as CustomEvent<{
+				root?: string;
+				state?: SharedNavigationState;
+			}>).detail;
+			if (detail?.root !== sharedRoot || !detail.state) return;
+			const serializedSharedState = JSON.stringify(detail.state);
+			if (serializedSharedState === lastSharedState) return;
+			lastSharedState = serializedSharedState;
+			applyDisclosureState(detail.state);
+		});
+		const controls = container.querySelector<HTMLElement>('[data-tree-controls]');
+		const filterInput = controls?.querySelector<HTMLInputElement>('[data-tree-filter]') ?? null;
+		const expandButton = controls?.querySelector<HTMLButtonElement>('[data-tree-expand-all]') ?? null;
+		const collapseButton = controls?.querySelector<HTMLButtonElement>('[data-tree-collapse-all]') ?? null;
+		const locateButton = controls?.querySelector<HTMLButtonElement>('[data-tree-locate-current]') ?? null;
+		const emptyMessage = controls?.querySelector<HTMLElement>('[data-tree-filter-empty]') ?? null;
+		const status = controls?.querySelector<HTMLElement>('[data-tree-status]') ?? null;
+		const currentPageNode = container.querySelector<HTMLElement>(
+			'.navigation-page-node[data-navigation-current-page="true"]',
+		);
+		const labels = {
+			collapsed: controls?.dataset.treeLabelCollapsed ?? '',
+			expanded: controls?.dataset.treeLabelExpanded ?? '',
+			filterMatches: controls?.dataset.treeLabelFilterMatches ?? '{count}',
+			located: controls?.dataset.treeLabelLocated ?? '',
+		};
+		const normalizeTitle = (value: string) => value
+			.normalize('NFKD')
+			.replace(/\p{Mark}+/gu, '')
+			.toLocaleLowerCase(document.documentElement.lang || undefined)
+			.trim();
+		const setStatus = (message: string) => {
+			if (status) status.textContent = message;
+		};
+		const getSnapshot = (): NavigationSnapshot => ({
+			branchOpen: branches.map((branch) => branch.open),
+			sectionOpen: sectionBranches.map((branch) => branch.open),
+			scrollTop: scrollContainer.scrollTop,
+		});
+		const revealNodeAndAncestors = (node: HTMLElement) => {
+			let currentNode: HTMLElement | null = node;
 
-		requestAnimationFrame(() => {
-			branches.forEach((branch) => branch.addEventListener('toggle', () => {
-				if (branch.open && branch.dataset.hasSections === 'true') {
-					branch.dataset.sectionsOpen = 'true';
-				} else if (!branch.open) {
-					delete branch.dataset.sectionsOpen;
+			while (currentNode && container.contains(currentNode)) {
+				currentNode.hidden = false;
+				const parentNode = currentNode.parentElement?.closest<HTMLElement>(
+					'.navigation-page-node[data-navigation-title]',
+				) ?? null;
+				const parentBranch = parentNode?.querySelector<HTMLDetailsElement>(
+					':scope > .navigation-page-disclosure[data-page-path]',
+				);
+				if (parentBranch) parentBranch.open = true;
+				currentNode = parentNode;
+			}
+		};
+		const restoreFilterSnapshot = () => {
+			if (!filterSnapshot) return;
+
+			branches.forEach((branch, index) => { branch.open = filterSnapshot?.branchOpen[index] ?? false; });
+			sectionBranches.forEach((branch, index) => { branch.open = filterSnapshot?.sectionOpen[index] ?? false; });
+			scrollContainer.scrollTop = filterSnapshot.scrollTop;
+			filterSnapshot = null;
+			requestAnimationFrame(saveState);
+		};
+		const clearFilter = () => {
+			navigationNodes.forEach((node) => { node.hidden = false; });
+			delete container.dataset.treeFilterActive;
+			if (emptyMessage) emptyMessage.hidden = true;
+			if (expandButton) expandButton.disabled = false;
+			if (collapseButton) collapseButton.disabled = false;
+			restoreFilterSnapshot();
+			setStatus('');
+		};
+		const applyFilter = () => {
+			const query = normalizeTitle(filterInput?.value ?? '');
+
+			if (!query) {
+				clearFilter();
+				return;
+			}
+
+			if (!filterSnapshot) filterSnapshot = getSnapshot();
+			container.dataset.treeFilterActive = 'true';
+			if (expandButton) expandButton.disabled = true;
+			if (collapseButton) collapseButton.disabled = true;
+			navigationNodes.forEach((node) => { node.hidden = true; });
+
+			const matches = navigationNodes.filter((node) => normalizeTitle(
+				node.dataset.navigationTitle ?? '',
+			).includes(query));
+			matches.forEach((node) => {
+				revealNodeAndAncestors(node);
+
+				if (node.dataset.navigationKind === 'category') {
+					node.querySelectorAll<HTMLElement>('.navigation-page-node[data-navigation-title]')
+						.forEach((descendant) => { descendant.hidden = false; });
+					const categoryBranch = node.querySelector<HTMLDetailsElement>(
+						':scope > .navigation-category-disclosure',
+					);
+					if (categoryBranch) categoryBranch.open = true;
 				}
-				saveState();
-			}));
+			});
+
+			if (matches.length === 0 && currentPageNode) revealNodeAndAncestors(currentPageNode);
+			if (emptyMessage) emptyMessage.hidden = matches.length > 0;
+			setStatus(labels.filterMatches.replace('{count}', String(matches.length)));
+		};
+		const setAllOpen = (open: boolean) => {
+			branches.forEach((branch) => { branch.open = open; });
+			sectionBranches.forEach((branch) => { branch.open = open; });
+			saveState();
+			setStatus(open ? labels.expanded : labels.collapsed);
+		};
+		const locateCurrentPage = () => {
+			if (!currentPageNode) return;
+
+			if (filterInput?.value) {
+				filterInput.value = '';
+				clearFilter();
+			}
+			revealNodeAndAncestors(currentPageNode);
+			currentPageNode.querySelectorAll<HTMLDetailsElement>(
+				':scope > .navigation-page-disclosure, :scope > .navigation-page-sections-disclosure',
+			).forEach((branch) => { branch.open = true; });
+			saveState();
+
+			const currentPageLink = currentPageNode.querySelector<HTMLAnchorElement>(
+				':scope > .navigation-page-link, :scope > .navigation-page-open-link',
+			);
+			if (!currentPageLink) return;
+
+			currentPageLink.focus({ preventScroll: true });
+			const scrollBox = scrollContainer.getBoundingClientRect();
+			const linkBox = currentPageLink.getBoundingClientRect();
+			scrollContainer.scrollTop += linkBox.top - scrollBox.top
+				- Math.max(0, (scrollContainer.clientHeight - linkBox.height) / 2);
+			setStatus(labels.located);
+		};
+		const openLinkedPage = (link: HTMLAnchorElement) => {
+			if (filterInput?.value) {
+				filterInput.value = '';
+				clearFilter();
+			}
+			const pageNode = link.closest<HTMLElement>('.navigation-page-node');
+			const pageDisclosure = pageNode?.querySelector<HTMLDetailsElement>(
+				':scope > .navigation-page-disclosure:not(.navigation-category-disclosure)',
+			);
+			const sectionDisclosure = pageNode?.querySelector<HTMLDetailsElement>(
+				':scope > .navigation-page-sections-disclosure[data-page-path]',
+			);
+
+			if (pageDisclosure) pageDisclosure.open = true;
+			if (sectionDisclosure) sectionDisclosure.open = true;
+			saveState();
+		};
+
+		requestAnimationFrame(() => {
+			branches.forEach((branch) => branch.addEventListener('toggle', saveState));
+			sectionBranches.forEach((branch) => branch.addEventListener('toggle', saveState));
 		});
 
-		container.addEventListener('scroll', saveState, { passive: true });
-		container.querySelectorAll('a').forEach((link) => link.addEventListener('click', saveState));
+		if (controls) controls.hidden = false;
+		if (locateButton && !currentPageNode) locateButton.disabled = true;
+		filterInput?.addEventListener('input', applyFilter);
+		filterInput?.addEventListener('keydown', (event) => {
+			if (event.key !== 'Escape' || !filterInput.value) return;
+			event.preventDefault();
+			filterInput.value = '';
+			clearFilter();
+		});
+		expandButton?.addEventListener('click', () => setAllOpen(true));
+		collapseButton?.addEventListener('click', () => setAllOpen(false));
+		locateButton?.addEventListener('click', locateCurrentPage);
+		scrollContainer.addEventListener('scroll', saveState, { passive: true });
+		container.querySelectorAll<HTMLAnchorElement>('.navigation-page-link, .navigation-page-open-link')
+			.forEach((link) => link.addEventListener('click', () => openLinkedPage(link)));
 		window.addEventListener('pagehide', saveState);
 	};
 

package/src/layouts/BaseLayout.astro

@@ -1,7 +1,7 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { getPresentationCssVariables } from '../../scripts/lib/presentation.mjs';
-import { getIconLinks } from '../lib/sitePublicAssets';
+import { getIconLinks, getSocialImageAsset } from '../lib/sitePublicAssets';
 import { withBasePath } from '../lib/basePath';
 import { getReaderPreferencesScript } from '../lib/readerPreferencesScript.mjs';
 import '../styles/global.css';
@@ -77,6 +77,8 @@ interface Props {
 		buildInfo?: boolean;
 	};
 	contentsNavigation?: boolean;
+	indexable?: boolean;
+	searchable?: boolean;
 }
 
 const {
@@ -88,11 +90,17 @@ const {
 	pathname = '/',
 	footer,
 	contentsNavigation = false,
+	indexable = true,
+	searchable = false,
 } = Astro.props;
 
 const documentTitle = title;
 const canonicalUrl = new URL(withBasePath(projectConfig.site.basePath, pathname), projectConfig.site.url).href;
 const iconLinks = getIconLinks();
+const socialImageAsset = getSocialImageAsset();
+const socialImageUrl = socialImageAsset
+	? new URL(withBasePath(projectConfig.site.basePath, socialImageAsset.href), projectConfig.site.url).href
+	: null;
 const scrollBehavior = projectConfig.navigation.scrollBehavior === 'smooth' ? 'smooth' : 'auto';
 const formatPercent = (value: number) => `${value}%`;
 const formatViewportHeightPercent = (value: number) => `${value}svh`;
@@ -132,6 +140,65 @@ const documentStyle = [
 		]
 		: []),
 ].join('; ');
+const marginNoteReadingWidths = [
+	['narrow', 'min(60ch, 680px)'],
+	['standard', 'min(72ch, 680px)'],
+	['wide', `min(80ch, ${visualTheme.images.width})`],
+] as const;
+const marginNoteOuterReserve = '0.5rem';
+const marginNoteDeclarations = [
+	'float: right;',
+	'clear: right;',
+	'width: var(--layout-note-width);',
+	'margin: 0 calc(0px - var(--layout-note-width) - var(--layout-note-gap)) 0.75rem var(--layout-note-gap);',
+].join('\n');
+const marginNoteLayoutCss = [
+	'@media (min-width: 1101px) {',
+	...marginNoteReadingWidths.flatMap(([readingWidth, textWidth]) => [
+		[
+			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap})) {`,
+			`:root[data-reading-width="${readingWidth}"] .site-page-layout:not(.site-page-layout-tree) .section-note {`,
+				marginNoteDeclarations,
+			'}',
+		'}',
+		].join('\n'),
+		[
+			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve} - 11rem - ${visualTheme.layout.localNavigationGap})) {`,
+			`:root[data-reader-preferences-ready="true"][data-reading-width="${readingWidth}"][data-focus-reading="on"] .site-page-layout-tree .section-note {`,
+				marginNoteDeclarations,
+			'}',
+		'}',
+		].join('\n'),
+	]),
+	'}',
+	'@media (min-width: 1101px) and (max-width: 1280px) {',
+	...marginNoteReadingWidths.map(([readingWidth, textWidth]) => [
+		`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve})) {`,
+		`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree:not(.site-page-layout-contents) .section-note {`,
+			marginNoteDeclarations,
+		'}',
+	'}',
+	].join('\n')),
+	'}',
+	'@media (min-width: 1281px) {',
+	...marginNoteReadingWidths.flatMap(([readingWidth, textWidth]) => [
+		[
+			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap})) {`,
+			`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree.site-page-layout-contents .section-note {`,
+				marginNoteDeclarations,
+			'}',
+		'}',
+		].join('\n'),
+		[
+			`@container (min-width: calc(${textWidth} + ${visualTheme.layout.noteWidth} + ${visualTheme.layout.noteGap} + ${marginNoteOuterReserve} - 11rem - ${visualTheme.layout.localNavigationGap})) {`,
+			`:root[data-reading-width="${readingWidth}"] .site-page-layout-tree:not(.site-page-layout-contents) .section-note {`,
+				marginNoteDeclarations,
+			'}',
+		'}',
+		].join('\n'),
+	]),
+	'}',
+].join('\n');
 const { buildInfo, copyrightMessage } = footer ?? {};
 const showBuildInfo = buildInfo === true;
 const buildTime = showBuildInfo
@@ -164,16 +231,29 @@ const readerPreferencesScript = readerPreferencesEnabled
 	data-reading-width={presentation.readerPreferences.defaults.readingWidth}
 	data-focus-reading={presentation.readerPreferences.defaults.focusReading}
 	data-section-tracking={contentsNavigation ? 'enabled' : undefined}
+	data-pagefind-ignore={searchable ? undefined : 'all'}
 	style={documentStyle}
 >
 	<head>
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 		<meta name="format-detection" content="telephone=no" />
+		{!indexable && <meta name="robots" content="noindex" />}
 		{description && <meta name="description" content={description} />}
+		{indexable && <meta property="og:type" content="website" />}
+		{indexable && <meta property="og:title" content={documentTitle} />}
+		{indexable && <meta property="og:url" content={canonicalUrl} />}
+		{indexable && description && <meta property="og:description" content={description} />}
+		{indexable && socialImageUrl && <meta property="og:image" content={socialImageUrl} />}
+		{indexable && socialImageAsset && <meta property="og:image:type" content={socialImageAsset.type} />}
+		{indexable && <meta name="twitter:card" content={socialImageUrl ? 'summary_large_image' : 'summary'} />}
+		{indexable && <meta name="twitter:title" content={documentTitle} />}
+		{indexable && description && <meta name="twitter:description" content={description} />}
+		{indexable && socialImageUrl && <meta name="twitter:image" content={socialImageUrl} />}
 		<meta name="theme-color" content={presentation.palette.page.backgroundColor} />
 		{readerPreferencesScript && <script is:inline set:html={readerPreferencesScript} />}
-		<link rel="canonical" href={canonicalUrl} />
+		<style is:inline set:html={marginNoteLayoutCss} />
+		{indexable && <link rel="canonical" href={canonicalUrl} />}
 		<meta name="generator" content={Astro.generator} />
 		{iconLinks.map((iconLink) => (
 			<link
@@ -183,6 +263,7 @@ const readerPreferencesScript = readerPreferencesEnabled
 				href={iconLink.href}
 			/>
 		))}
+		<slot name="head" />
 		<title>{documentTitle}</title>
 	</head>
 	<body>

package/src/lib/generatedImages.ts

@@ -45,6 +45,24 @@ export const getGeneratedImage = (src: string) => readGeneratedImages()[src];
 
 const displaySrc = (src: string) => withBasePath(projectConfig.site.basePath, src);
 
+export const getImageInspectionAttributes = (src: string) => {
+	const image = getGeneratedImage(src);
+	const largestVariant = image?.variants
+		? [...image.variants].sort((left, right) => left.width - right.width).at(-1)
+		: undefined;
+	const publishedSource = image?.kind === 'static'
+		? image.src
+		: largestVariant?.src;
+
+	return {
+		href: displaySrc(publishedSource ?? src),
+		scalable: image?.kind === 'static' || /\.svg(?:[?#]|$)/iu.test(publishedSource ?? src),
+		...(Number.isFinite(image?.width) && Number.isFinite(image?.height)
+			? { width: image?.width, height: image?.height }
+			: {}),
+	};
+};
+
 const getDisplayVariants = (variants: NonNullable<GeneratedImage['variants']>) => {
 	const sortedVariants = [...variants].sort((a, b) => a.width - b.width);
 	const displayVariants = sortedVariants.filter((variant) => variant.width <= maxDisplayImageWidth);

package/src/lib/sectionContent.ts

@@ -3,6 +3,7 @@ import projectConfig from '../../scripts/lib/project-config.mjs';
 import {
 	formatHeadingIdentifierIssue,
 } from '../../scripts/lib/heading-ids.mjs';
+import { splitNornaRenderedBlocks } from '../../scripts/lib/norna-markdown-blocks.mjs';
 import { applyBasePathToHtml } from './basePath';
 import type { SitePage } from './sitePages';
 
@@ -36,7 +37,16 @@ type ParsedCardListBlock = {
 	width?: CardListWidth;
 	cards: CardListItem[];
 };
-type ParsedNornaBlock = ParsedImageBlock | ParsedCardListBlock;
+type ParsedPageListBlock = {
+	type: 'page-list';
+	line: number;
+};
+type ParsedNornaBlock = ParsedImageBlock | ParsedCardListBlock | ParsedPageListBlock;
+type PageListItem = {
+	title: string;
+	pathname: string;
+	description?: string;
+};
 type InlineNote = {
 	markdown: string;
 	number: number;
@@ -48,7 +58,8 @@ type SectionContentBlock =
 	| { type: 'html'; html: string }
 	| { type: 'image-stack'; images: ManagedImage[] }
 	| { type: 'image-carousel'; images: ManagedImage[] }
-	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width?: CardListWidth; cards: CardListItem[] };
+	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width?: CardListWidth; cards: CardListItem[] }
+	| { type: 'page-list'; pages: PageListItem[] };
 export type ResolvedSection = {
 	id: string | null;
 	title: string;
@@ -192,36 +203,11 @@ const splitRenderedRegions = (html: string, regionCount: number) => {
 	});
 };
 
-const splitNornaBlockMarkers = (html: string, blocks: ParsedNornaBlock[]) => {
-	const result: Array<{ type: 'html'; html: string } | ParsedNornaBlock> = [];
-	const markerRegex = /<norna-block\s+data-index="(\d+)"\s*><\/norna-block>/g;
-	const seen = new Set<number>();
-	let cursor = 0;
-
-	for (const match of html.matchAll(markerRegex)) {
-		const start = match.index ?? 0;
-		if (start > cursor) result.push({ type: 'html', html: html.slice(cursor, start) });
-
-		const index = Number.parseInt(match[1] ?? '', 10);
-		const block = blocks[index];
-		if (!block) throw new Error(`Rendered Norna block ${index + 1} has no matching parsed block.`);
-		seen.add(index);
-		result.push(block);
-		cursor = start + match[0].length;
-	}
-
-	if (cursor < html.length) result.push({ type: 'html', html: html.slice(cursor) });
-	if (seen.size !== blocks.length) {
-		throw new Error(`Rendered Markdown contains ${seen.size} Norna block markers, but ${blocks.length} blocks were parsed.`);
-	}
-
-	return result.filter((block) => block.type !== 'html' || block.html.trim());
-};
-
 const resolveContentBlocks = async (
 	html: string,
 	blocks: ParsedNornaBlock[],
 	page: SitePage,
+	childPages: SitePage[],
 	inlineNotes: InlineNote[] = [],
 ) => {
 	const renderedNotes = await Promise.all(inlineNotes.map(async (note) => ({
@@ -229,7 +215,9 @@ const resolveContentBlocks = async (
 		html: await renderInlineNoteMarkdown(note.markdown),
 	})));
 	const renderedHtml = applyInlineNoteMarkup(html, renderedNotes);
-	const splitBlocks = splitNornaBlockMarkers(renderedHtml, blocks);
+	const splitBlocks = splitNornaRenderedBlocks(renderedHtml, blocks) as Array<
+		{ type: 'html'; html: string } | ParsedNornaBlock
+	>;
 	const resolvedBlocks: SectionContentBlock[] = [];
 
 	for (const block of splitBlocks) {
@@ -252,6 +240,20 @@ const resolveContentBlocks = async (
 			});
 			continue;
 		}
+		if (block.type === 'page-list') {
+			if (childPages.length === 0) {
+				throw new Error(`${page.contentLabel} line ${block.line}: page-list has no listed direct child pages to display. Navigation categories are not pages. Add a listed direct child page or remove the block.`);
+			}
+			resolvedBlocks.push({
+				type: 'page-list',
+				pages: childPages.map((childPage) => ({
+					title: childPage.title,
+					pathname: childPage.pathname,
+					description: childPage.entry.data.page?.description,
+				})),
+			});
+			continue;
+		}
 
 		resolvedBlocks.push({
 			type: block.type,
@@ -268,6 +270,7 @@ const resolveContentBlocks = async (
 export const getSectionsContent = async (
 	html: string,
 	page: SitePage,
+	childPages: SitePage[] = [],
 ) => {
 	const pageDocument = page.markdownDocument;
 	const sourceLabel = page.contentLabel;
@@ -307,6 +310,9 @@ export const getSectionsContent = async (
 		if (bodySection.noteErrors.length > 0) {
 			throw new Error(bodySection.noteErrors[0].message);
 		}
+		if (bodySection.calloutErrors.length > 0) {
+			throw new Error(bodySection.calloutErrors[0].message);
+		}
 
 		const inlineNotes = bodySection.notes.map((note) => {
 			const number = nextNoteNumber;
@@ -326,7 +332,7 @@ export const getSectionsContent = async (
 			title,
 			titleHtml: await renderHeadingTitleHtml(bodySection.heading.source),
 			headingLevel,
-			contentBlocks: await resolveContentBlocks(content, bodySection.blocks, page, inlineNotes),
+			contentBlocks: await resolveContentBlocks(content, bodySection.blocks, page, childPages, inlineNotes),
 		});
 	}