@janga/norna 0.7.16 → 0.7.17

package/src/components/SiteSection.astro

@@ -35,34 +35,36 @@ interface Props {
 	pagePresentation: ResolvedPagePresentation;
 	visualTheme: VisualTheme;
 	sectionIndex: number;
-	headingLevel: 1 | 2;
 	prioritizeFirstImage?: boolean;
 }
 
-const { section, pagePresentation, visualTheme, sectionIndex, headingLevel, prioritizeFirstImage = false } = Astro.props;
-const HeadingTag = headingLevel === 1 ? 'h1' : 'h2';
-// Sections are authored with Markdown ## headings even when the first one renders as HTML h1.
-const sectionHeadingVisualLevel = 'h2';
-const firstContentBlockIsVisual = section.contentBlocks[0]?.type !== 'html'
-	&& section.contentBlocks[0]?.type !== 'note';
+const { section, pagePresentation, visualTheme, sectionIndex, prioritizeFirstImage = false } = Astro.props;
+const isPageTitle = section.headingLevel === 1;
+const HeadingTag = section.headingLevel === 1 ? 'h1' : 'h2';
+const sectionHeadingVisualLevel = section.headingLevel === 1 ? 'h1' : 'h2';
+const headingId = section.id ?? 'page-title';
+const firstContentBlock = section.contentBlocks[0];
+const firstContentBlockIsVisual = firstContentBlock !== undefined
+	&& firstContentBlock.type !== 'html'
+	&& firstContentBlock.type !== 'note';
 type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4';
 const headingSizeValues: Record<HeadingLevel, Record<TextSize, ResponsiveValue<string>>> = {
 	h1: {
 		small: {
-			desktop: 'clamp(1.5rem, 1.18rem + 1.15vw, 2.25rem)',
-			mobile: 'clamp(1.42rem, 1.12rem + 1.5vw, 2rem)',
+			desktop: 'clamp(1.35rem, 1.2rem + 0.55vw, 1.7rem)',
+			mobile: 'clamp(1.32rem, 1.16rem + 0.8vw, 1.58rem)',
 		},
 		medium: {
-			desktop: 'clamp(1.85rem, 1.35rem + 1.8vw, 3.1rem)',
-			mobile: 'clamp(1.65rem, 1.18rem + 2.2vw, 2.45rem)',
+			desktop: 'clamp(1.65rem, 1.35rem + 1.1vw, 2.4rem)',
+			mobile: 'clamp(1.5rem, 1.22rem + 1.4vw, 2rem)',
 		},
 		large: {
-			desktop: 'clamp(2.25rem, 1.45rem + 2.75vw, 4.25rem)',
-			mobile: 'clamp(1.9rem, 1.26rem + 3.2vw, 3.15rem)',
+			desktop: 'clamp(1.95rem, 1.48rem + 1.7vw, 3.2rem)',
+			mobile: 'clamp(1.75rem, 1.32rem + 2.15vw, 2.5rem)',
 		},
 		xlarge: {
-			desktop: 'clamp(2.75rem, 1.6rem + 3.8vw, 5.5rem)',
-			mobile: 'clamp(2.2rem, 1.35rem + 4.4vw, 3.9rem)',
+			desktop: 'clamp(2.35rem, 1.58rem + 2.75vw, 4.4rem)',
+			mobile: 'clamp(2rem, 1.4rem + 3vw, 3.1rem)',
 		},
 	},
 	h2: {
@@ -168,7 +170,9 @@ const textWidthValues: Record<TextWidth, string> = {
 	normal: 'min(72ch, var(--text-width))',
 	wide: 'min(72ch, var(--image-layout-width))',
 };
-const surface = resolveSectionSurface(pagePresentation, sectionIndex);
+const surface = isPageTitle
+	? pagePresentation.palette.surfaces.base
+	: resolveSectionSurface(pagePresentation, sectionIndex);
 const typography = pagePresentation.typography.values;
 const heading = typography.headings[sectionHeadingVisualLevel] as {
 	align: ResponsiveValue<TextAlign>;
@@ -249,6 +253,7 @@ for (const block of section.contentBlocks) {
 }
 
 flushReadingBlocks();
+const firstMediaGroupIndex = contentGroups.findIndex((group) => group.type === 'media');
 const markdownHeadingStyle = (level: 'h3' | 'h4') => {
 	const headingConfig = markdownHeadings[level];
 	const fontSize = getHeadingSizeValue(level, headingConfig.size);
@@ -298,10 +303,12 @@ const sectionStyle = [
 ---
 
 <section
-	aria-labelledby={section.id}
+	aria-labelledby={headingId}
 	class:list={[
 		'site-section',
 		{
+			'site-section-page-title': isPageTitle,
+			'site-section-page-title-empty': isPageTitle && section.contentBlocks.length === 0,
 			'site-section-first-block-is-visual': firstContentBlockIsVisual,
 			'site-section-has-margin-notes': hasMarginNotes,
 		},
@@ -311,7 +318,7 @@ const sectionStyle = [
 >
 	<div class="section-card">
 		<header class="section-header">
-			<HeadingTag id={section.id} set:html={section.titleHtml} />
+			<HeadingTag id={headingId} set:html={section.titleHtml} />
 		</header>
 
 		<div class:list={['section-body', { 'section-body-has-media': hasMedia, 'section-body-text-only': !hasMedia }]}>
@@ -381,7 +388,7 @@ const sectionStyle = [
 							title={section.title}
 							images={block.images}
 							maxAvailableWidthPercent={visualTheme.images.maxAvailableWidthPercent}
-							priorityFirstImage={prioritizeFirstImage && groupIndex === 0}
+							priorityFirstImage={prioritizeFirstImage && groupIndex === firstMediaGroupIndex}
 						/>
 					);
 				}
@@ -395,7 +402,7 @@ const sectionStyle = [
 						title={section.title}
 						images={block.images}
 						maxAvailableWidthPercent={visualTheme.images.maxAvailableWidthPercent}
-						priorityFirstImage={prioritizeFirstImage && groupIndex === 0}
+						priorityFirstImage={prioritizeFirstImage && groupIndex === firstMediaGroupIndex}
 					/>
 				);
 			})}

package/src/content.config.ts

@@ -8,7 +8,7 @@ import {
 	siteThemePath,
 	sitewideContentPath,
 } from '../scripts/lib/site-paths.mjs';
-import { parseRouteDirectory } from '../scripts/lib/route-model.mjs';
+import { encodePageDirectoryPath, parsePageDirectoryPath } from '../scripts/lib/page-model.mjs';
 import {
 	siteSchema,
 	sitewideSchema,
@@ -23,16 +23,20 @@ const siteThemeSchema = themeVisualSchema;
 
 const site = defineCollection({
 	loader: glob({
-		pattern: ['content.md', 'routes/*/content.md'],
+		pattern: ['content.md', 'pages/**/content.md'],
 		base: pathToFileURL(siteDir),
 		generateId: ({ entry }) => {
 			if (entry === 'content.md') {
 				return siteEntryId;
 			}
 
-			const routeDirectory = entry.match(/^routes\/([^/]+)\/content\.md$/)?.[1];
-			return routeDirectory
-				? `${siteEntryId.replace(/-content$/, '')}-route-${parseRouteDirectory(routeDirectory, `route directory routes/${routeDirectory}`).routeDirectory}`
+			const pageEntryDirectory = entry.split('/').slice(1, -1).join('/');
+			const pageDirectory = pageEntryDirectory
+				.split('/')
+				.filter((segment) => segment !== 'pages')
+				.join('/pages/');
+			return pageDirectory
+				? `${siteEntryId.replace(/-content$/, '')}-page-${encodePageDirectoryPath(parsePageDirectoryPath(pageDirectory, `page directory pages/${pageEntryDirectory}`).pageDirectory)}`
 				: entry.replace(/[^a-zA-Z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
 		},
 	}),

package/src/layouts/BaseLayout.astro

@@ -39,7 +39,7 @@ type VisualTheme = {
 };
 
 interface Props {
-	title?: string;
+	title: string;
 	description?: string;
 	presentation: Presentation;
 	visualTheme: VisualTheme;
@@ -47,22 +47,13 @@ interface Props {
 	pathname?: string;
 	footer?: {
 		copyrightMessage?: string;
-		buildInfo?: {
-			enabled: boolean;
-			text: string;
-			dateTimeFormat: {
-				locale: string;
-				timeZone: string;
-				dateStyle: string;
-				timeStyle: string;
-			};
-		};
+		buildInfo?: boolean;
 	};
 }
 
 const {
-	title = 'norna',
-	description = 'A norna site.',
+	title,
+	description,
 	presentation,
 	visualTheme,
 	frameColors,
@@ -103,12 +94,12 @@ const documentStyle = [
 	`--image-max-height-mobile: ${formatViewportHeightPercent(visualTheme.images.maxAvailableHeightPercent.mobile)}`,
 ].join('; ');
 const { buildInfo, copyrightMessage } = footer ?? {};
-const showBuildInfo = Boolean(buildInfo?.enabled);
+const showBuildInfo = buildInfo === true;
 const buildTime = showBuildInfo
-	? new Intl.DateTimeFormat(buildInfo.dateTimeFormat.locale, {
-		dateStyle: buildInfo.dateTimeFormat.dateStyle,
-		timeStyle: buildInfo.dateTimeFormat.timeStyle,
-		timeZone: buildInfo.dateTimeFormat.timeZone,
+	? new Intl.DateTimeFormat(projectConfig.locale.lang, {
+		dateStyle: 'short',
+		timeStyle: 'short',
+		timeZone: 'UTC',
 	}).format(new Date())
 	: null;
 const showFooter = Boolean(copyrightMessage || showBuildInfo);
@@ -124,7 +115,7 @@ const footerStyle = [
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 		<meta name="format-detection" content="telephone=no" />
-		<meta name="description" content={description} />
+		{description && <meta name="description" content={description} />}
 		<meta name="theme-color" content={presentation.palette.page.backgroundColor} />
 		<link rel="canonical" href={canonicalUrl} />
 		<meta name="generator" content={Astro.generator} />
@@ -144,7 +135,7 @@ const footerStyle = [
 			<footer class="site-footer" style={footerStyle}>
 				<p>
 					{copyrightMessage}
-					{showBuildInfo && <span>{buildInfo.text} {buildTime}</span>}
+					{showBuildInfo && <span>{projectConfig.locale.labels.built} {buildTime}</span>}
 				</p>
 			</footer>
 		)}

package/src/lib/pageThemes.ts

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+	validatePageThemeYamlStructure,
+} from '../../scripts/lib/site-content.mjs';
+import { sitePagesDir, sitePagesLabel } from '../../scripts/lib/site-paths.mjs';
+import { parseYamlConfig } from '../../scripts/lib/yaml-config.mjs';
+import { getPageDirectoryAncestors } from '../../scripts/lib/page-model.mjs';
+
+type PageTheme = {
+	id: string;
+	data: Record<string, unknown>;
+};
+
+export const getPageTheme = async (pageDirectory: string | null): Promise<PageTheme | null> => {
+	if (!pageDirectory) return null;
+
+	const pageAncestors = getPageDirectoryAncestors(pageDirectory).reverse();
+	for (const pageAncestor of pageAncestors) {
+		const themeSegments = pageAncestor.split('/');
+		const themePath = path.join(sitePagesDir, ...themeSegments, 'theme.yaml');
+		const source = await readFile(themePath, 'utf8').catch((error) => {
+			if (error?.code === 'ENOENT') return null;
+			throw error;
+		});
+		if (!source) continue;
+		const themeLabel = `${sitePagesLabel}/${themeSegments.join('/')}/theme.yaml`;
+
+		const data = parseYamlConfig(source, themeLabel, {
+			validateStructure: validatePageThemeYamlStructure,
+		});
+		if (Object.hasOwn(data, 'navigation')) {
+			throw new Error(`${themeLabel} may not define navigation. Set the site-wide navigation mode in the root theme.yaml.`);
+		}
+		return {
+			id: `pages/${themeSegments.join('/')}/theme`,
+			data,
+		};
+	}
+
+	return null;
+};

package/src/lib/sectionContent.ts

@@ -1,6 +1,10 @@
-import type { CollectionEntry } from 'astro:content';
 import { markdownToHtml } from 'satteri';
 import projectConfig from '../../scripts/lib/project-config.mjs';
+import {
+	formatHeadingIdentifierIssue,
+	getHeadingIdentifierIssues,
+} from '../../scripts/lib/heading-ids.mjs';
+import { getBodySections } from '../../scripts/lib/site-content.mjs';
 import {
 	extractInlineNoteDiagnostics,
 	extractNornaMarkdownBlocks,
@@ -10,8 +14,6 @@ import {
 import { applyBasePathToHtml } from './basePath';
 import type { SitePage } from './sitePages';
 
-type SiteSectionMetadataMap = CollectionEntry<'site'>['data']['sections'];
-type SiteSectionMetadata = SiteSectionMetadataMap[string];
 type ManagedImage = {
 	image: string;
 	src: string;
@@ -42,10 +44,11 @@ type SectionContentBlock =
 	| { type: 'image-carousel'; images: ManagedImage[] }
 	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width: CardListWidth; cards: CardListItem[] }
 	| { type: 'note'; html: string; number?: number; id?: string; referenceId?: string };
-export type ResolvedSection = SiteSectionMetadata & {
-	id: string;
+export type ResolvedSection = {
+	id: string | null;
 	title: string;
 	titleHtml: string;
+	headingLevel: 1 | 2;
 	contentBlocks: SectionContentBlock[];
 };
 
@@ -54,9 +57,13 @@ export type SectionNavigation = {
 	title: string;
 };
 
-const headingRegex = /<h2\b([^>]*)>([\s\S]*?)<\/h2>/gi;
+export type HeadingNavigation = SectionNavigation & {
+	depth: 2 | 3;
+	parentId: string | null;
+};
+
+const contentHeadingRegex = /<h([12])\b([^>]*)>([\s\S]*?)<\/h\1>/gi;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
-const markdownH2Regex = /^##\s+.*$/gm;
 const imageProvenanceCommentRegex = /<!--\s*norna-image-provenance:[\s\S]*?-->/gi;
 
 const stripTags = (html: string) => html.replace(/<[^>]*>/g, '');
@@ -69,69 +76,43 @@ const decodeHtmlEntities = (value: string) =>
 		.replace(/&quot;/g, '"')
 		.replace(/&#39;/g, "'");
 
-const slugify = (value: string) =>
-	decodeHtmlEntities(stripTags(value))
-		.trim()
-		.toLowerCase()
-		.normalize('NFD')
-		.replace(/[\u0300-\u036f]/g, '')
-		.replace(/å/g, 'a')
-		.replace(/ä/g, 'a')
-		.replace(/ö/g, 'o')
-		.replace(/[^a-z0-9]+/g, '-')
-		.replace(/^-+|-+$/g, '');
-
-const getHeadingId = (attributes: string, headingHtml: string) => {
-	const headingText = decodeHtmlEntities(stripTags(headingHtml)).trim();
-	const explicitId = headingText.match(explicitHeadingIdRegex)?.[1];
-	if (explicitId) return explicitId;
-
-	const id = attributes.match(/\sid=(["'])(.*?)\1/i)?.[2];
-	return id ? decodeHtmlEntities(id) : slugify(headingHtml);
-};
-
-const getExplicitHeadingId = (headingHtml: string) =>
-	decodeHtmlEntities(stripTags(headingHtml)).trim().match(explicitHeadingIdRegex)?.[1];
-
 const getHeadingTitle = (headingHtml: string) =>
 	decodeHtmlEntities(stripTags(headingHtml)).replace(explicitHeadingIdRegex, '').trim();
 
 const getHeadingTitleHtml = (headingHtml: string) =>
 	prepareContentHtml(headingHtml.replace(explicitHeadingIdRegex, '').trim());
 
-export const getSectionNavigation = (html: string, sectionMetadata: SiteSectionMetadataMap): SectionNavigation[] => {
-	const matches = Array.from(html.matchAll(headingRegex));
-	const sectionIds = new Set<string>();
-	const sections = matches.map((match) => {
-		const attributes = match[1] ?? '';
-		const headingHtml = match[2] ?? '';
-		const explicitId = getExplicitHeadingId(headingHtml);
-		const id = getHeadingId(attributes, headingHtml);
-		const title = getHeadingTitle(headingHtml);
-
-		if (!explicitId) {
-			throw new Error(`Section heading "${title}" is missing an explicit id. Write it as: ## ${title} {#${id}}`);
-		}
-
-		if (sectionIds.has(id)) {
-			throw new Error(`Duplicate Markdown section heading id: ${id}`);
-		}
-
-		sectionIds.add(id);
-		return { id, title };
+export const getHeadingNavigation = async (
+	markdown: string,
+	sourceLabel = 'Markdown',
+): Promise<HeadingNavigation[]> => {
+	const bodyStructure = await getBodySections(markdown);
+	const issues = getHeadingIdentifierIssues(bodyStructure.headings);
+	if (issues.length > 0) throw new Error(formatHeadingIdentifierIssue(issues[0], sourceLabel));
+
+	let parentId: string | null = null;
+	return bodyStructure.headings.flatMap((heading) => {
+		if (heading.depth === 1 || !heading.id) return [];
+		if (heading.depth === 2) parentId = heading.id;
+
+		return [{
+			depth: heading.depth,
+			id: heading.id,
+			parentId: heading.depth === 3 ? parentId : null,
+			title: heading.title,
+		}];
 	});
-
-	for (const id of Object.keys(sectionMetadata)) {
-		if (!sectionIds.has(id)) {
-			throw new Error(
-				`Section metadata "${id}" does not match any Markdown section. Add "## Heading {#${id}}" or remove sections.${id}.`,
-			);
-		}
-	}
-
-	return sections;
 };
 
+export const getSectionNavigation = async (
+	markdown: string,
+	sourceLabel = 'Markdown',
+): Promise<SectionNavigation[]> => (
+	(await getHeadingNavigation(markdown, sourceLabel))
+		.filter((heading) => heading.depth === 2)
+		.map(({ id, title }) => ({ id, title }))
+);
+
 const stripImageProvenanceComments = (html: string) => html.replace(imageProvenanceCommentRegex, '');
 
 const prepareContentHtml = (html: string) =>
@@ -231,29 +212,44 @@ const applyInlineNoteMarkup = (html: string, notes: InlineNote[]) => {
 	});
 };
 
-const getRawMarkdownSections = (markdown: string) => {
-	const matches = Array.from(markdown.matchAll(markdownH2Regex));
+const getRawMarkdownSections = (bodySections: Awaited<ReturnType<typeof getBodySections>>['sections']) => {
 	const sections = new Map<string, string>();
 
-	for (let index = 0; index < matches.length; index += 1) {
-		const match = matches[index];
-		const heading = match[0] ?? '';
-		const id = heading.match(explicitHeadingIdRegex)?.[1];
+	for (const section of bodySections) {
+		const id = section.isPageTitle ? '__page-title' : section.id;
 		if (!id) continue;
-
-		const start = match.index ?? 0;
-		const next = matches[index + 1];
-		const end = next?.index ?? markdown.length;
-		sections.set(id, markdown.slice(start, end));
+		sections.set(id, section.text);
 	}
 
 	return sections;
 };
 
-const getImageSourceKey = (page: SitePage, sectionId: string, image: string) => (
-	page.routeDirectory
-		? `routes/${page.routeDirectory}/images/${sectionId}/${image}`
-		: `images/${sectionId}/${image}`
+const applyH3HeadingIds = (
+	html: string,
+	headings: Awaited<ReturnType<typeof getBodySections>>['headings'],
+) => {
+	let headingIndex = 0;
+	const result = html.replace(/<h3\b([^>]*)>([\s\S]*?)<\/h3>/gi, (_match, attributes, headingHtml) => {
+		const heading = headings[headingIndex];
+		headingIndex += 1;
+		if (!heading?.id) throw new Error('Rendered Markdown H3 could not be matched to its heading id.');
+
+		const cleanAttributes = String(attributes).replace(/\s+id=(["']).*?\1/gi, '');
+		const cleanHeadingHtml = String(headingHtml).replace(explicitHeadingIdRegex, '').trim();
+		return `<h3${cleanAttributes} id="${heading.id}">${cleanHeadingHtml}</h3>`;
+	});
+
+	if (headingIndex !== headings.length) {
+		throw new Error('Markdown H3 headings could not be matched to the rendered page content.');
+	}
+
+	return result;
+};
+
+const getImageSourceKey = (page: SitePage, image: string) => (
+	page.pageDirectory
+		? `pages/${page.pageDirectory}/images/${image}`
+		: `images/${image}`
 );
 
 const renderInlineNoteMarkdown = async (markdown: string) => {
@@ -275,7 +271,6 @@ const resolveContentBlocks = async (
 	html: string,
 	rawMarkdown: string,
 	page: SitePage,
-	sectionId: string,
 	inlineNotes: InlineNote[] = [],
 ) => {
 	const rawBlocks = extractNornaMarkdownBlocks(rawMarkdown);
@@ -323,7 +318,7 @@ const resolveContentBlocks = async (
 				width: block.width,
 				cards: block.cards.map((card: CardListItem) => ({
 					...card,
-					...(card.image ? { src: getImageSourceKey(page, sectionId, card.image) } : {}),
+					...(card.image ? { src: getImageSourceKey(page, card.image) } : {}),
 				})),
 			});
 			continue;
@@ -333,7 +328,7 @@ const resolveContentBlocks = async (
 			type: block.type,
 			images: block.images.map((image: { image: string; alt?: string; caption?: string }) => ({
 				...image,
-				src: getImageSourceKey(page, sectionId, image.image),
+				src: getImageSourceKey(page, image.image),
 			})),
 		});
 	}
@@ -344,38 +339,54 @@ const resolveContentBlocks = async (
 export const getSectionsContent = async (
 	html: string,
 	rawMarkdown: string,
-	sectionMetadata: SiteSectionMetadataMap,
 	page: SitePage,
+	sourceLabel = 'Markdown',
 ) => {
-	const matches = Array.from(html.matchAll(headingRegex));
-	const rawSections = getRawMarkdownSections(rawMarkdown);
-	const metadataIds = new Set(Object.keys(sectionMetadata));
+	const matches = Array.from(html.matchAll(contentHeadingRegex));
+	const bodyStructure = await getBodySections(rawMarkdown);
+	const headingIdentifierIssues = getHeadingIdentifierIssues(bodyStructure.headings);
+	if (headingIdentifierIssues.length > 0) {
+		throw new Error(formatHeadingIdentifierIssue(headingIdentifierIssues[0], sourceLabel));
+	}
+	const rawSections = getRawMarkdownSections(bodyStructure.sections);
 	const sections: ResolvedSection[] = [];
 	const sectionIds = new Set<string>();
 	let nextNoteNumber = 1;
+	const pageHeadingCount = matches.filter((match) => match[1] === '1').length;
+
+	if (pageHeadingCount !== 1 || matches[0]?.[1] !== '1') {
+		throw new Error('Each Norna page must start with exactly one Markdown H1 page title, for example "# About".');
+	}
 
 	for (let index = 0; index < matches.length; index += 1) {
 		const match = matches[index];
-		const attributes = match[1] ?? '';
-		const headingHtml = match[2] ?? '';
-		const explicitId = getExplicitHeadingId(headingHtml);
-		const id = getHeadingId(attributes, headingHtml);
+		const bodySection = bodyStructure.sections[index];
+		const headingLevel = Number.parseInt(match[1] ?? '', 10) as 1 | 2;
+		const headingHtml = match[3] ?? '';
+		if (!bodySection || bodySection.level !== headingLevel) {
+			throw new Error('Markdown H1/H2 headings could not be matched to the rendered page content.');
+		}
+		const id = bodySection.id;
 		const contentStart = (match.index ?? 0) + match[0].length;
 		const nextMatch = matches[index + 1];
 		const contentEnd = nextMatch?.index ?? html.length;
-		const content = html.slice(contentStart, contentEnd).trim();
+		const nextBodySection = bodyStructure.sections[index + 1];
+		const h3Headings = bodyStructure.headings.filter((heading) => (
+			heading.depth === 3
+			&& heading.index > bodySection.index
+			&& heading.index < (nextBodySection?.index ?? Number.POSITIVE_INFINITY)
+		));
+		const content = applyH3HeadingIds(html.slice(contentStart, contentEnd).trim(), h3Headings);
 		const title = getHeadingTitle(headingHtml);
 
-		if (!explicitId) {
-			throw new Error(`Section heading "${title}" is missing an explicit id. Write it as: ## ${title} {#${id}}`);
-		}
+		if (headingLevel === 2 && !id) throw new Error(`Section heading "${title}" cannot produce an automatic ASCII id.`);
 
-		if (sectionIds.has(id)) {
+		if (id && sectionIds.has(id)) {
 			throw new Error(`Duplicate Markdown section heading id: ${id}`);
 		}
 
-		sectionIds.add(id);
-		const rawSection = rawSections.get(id) ?? '';
+		if (id) sectionIds.add(id);
+		const rawSection = rawSections.get(id ?? '__page-title') ?? '';
 		const inlineNoteDiagnostics = extractInlineNoteDiagnostics(rawSection, {
 			label: 'Markdown section',
 		});
@@ -386,8 +397,8 @@ export const getSectionsContent = async (
 		const inlineNotes = inlineNoteDiagnostics.notes.map((note) => {
 			const number = nextNoteNumber;
 			nextNoteNumber += 1;
-			const pageKey = page.routeId || 'home';
-			const noteKey = `${pageKey}-${id}-${number}`;
+			const pageKey = page.pageId || 'home';
+			const noteKey = `${pageKey}-${id ?? 'page-title'}-${number}`;
 			return {
 				...note,
 				number,
@@ -397,21 +408,13 @@ export const getSectionsContent = async (
 		});
 
 		sections.push({
-			...(sectionMetadata[id] ?? {}),
 			id,
 			title,
 			titleHtml: getHeadingTitleHtml(headingHtml),
-			contentBlocks: await resolveContentBlocks(content, rawSection, page, id, inlineNotes),
+			headingLevel,
+			contentBlocks: await resolveContentBlocks(content, rawSection, page, inlineNotes),
 		});
 	}
 
-	for (const id of metadataIds) {
-		if (!sectionIds.has(id)) {
-			throw new Error(
-				`Section metadata "${id}" does not match any Markdown section. Add "## Heading {#${id}}" or remove sections.${id}.`,
-			);
-		}
-	}
-
 	return sections;
 };

package/src/lib/siteNavigation.ts

@@ -0,0 +1,48 @@
+import type { SectionNavigation } from './sectionContent';
+import type { SitePage } from './sitePages';
+
+export type PageNavigationEntry = {
+	page: SitePage;
+	sections: SectionNavigation[];
+};
+
+export type PageNavigationNode = PageNavigationEntry & {
+	children: PageNavigationNode[];
+};
+
+export const getPageNavigationTree = (entries: PageNavigationEntry[]) => {
+	const nodes = new Map<string, PageNavigationNode>();
+	const roots: PageNavigationNode[] = [];
+
+	for (const entry of entries) {
+		nodes.set(entry.page.pagePath, { ...entry, children: [] });
+	}
+
+	for (const entry of entries) {
+		const node = nodes.get(entry.page.pagePath);
+		if (!node) continue;
+
+		if (entry.page.isHome || entry.page.parentPagePath === null) {
+			roots.push(node);
+			continue;
+		}
+
+		const parent = nodes.get(entry.page.parentPagePath);
+		if (!parent) {
+			throw new Error(`Page "${entry.page.pathname}" has no parent page "${entry.page.parentPagePath}".`);
+		}
+
+		parent.children.push(node);
+	}
+
+	return roots;
+};
+
+export const getListedPageNavigationTree = (entries: PageNavigationEntry[]) => {
+	const filterListed = (nodes: PageNavigationNode[]): PageNavigationNode[] => nodes.flatMap((node) => {
+		if (!node.page.isHome && !node.page.navigation.listed) return [];
+		return [{ ...node, children: filterListed(node.children) }];
+	});
+
+	return filterListed(getPageNavigationTree(entries));
+};