@janga/norna 0.7.16 → 0.7.17

package/scripts/sync-content-sections.mjs

@@ -13,7 +13,6 @@ import {
 import {
 	getBodySections,
 	getContentFiles,
-	getFrontmatterSections,
 	getImageCandidatesByName,
 	getDeprecatedInlineStyleReferences,
 	readSiteFile,
@@ -23,6 +22,7 @@ import {
 	validateFrontmatterIndentation,
 	validateThemeYamlStructure,
 } from './lib/site-content.mjs';
+import { getHeadingIdentifierIssues } from './lib/heading-ids.mjs';
 import { readImageDimensions } from './lib/image-dimensions.mjs';
 import {
 	siteThemeLabel,
@@ -65,7 +65,7 @@ const promptForWrite = async () => {
 	if (!process.stdin.isTTY) return false;
 
 	const rl = createInterface({ input, output });
-	const answer = await rl.question('This will move image files into the page or route image roots where Norna references them. Continue? [y/N] ');
+	const answer = await rl.question('This will move image files into the page image roots where Norna references them. Continue? [y/N] ');
 	rl.close();
 
 	return answer.trim().toLowerCase() === 'y';
@@ -136,7 +136,7 @@ const getReportLines = (title, unreferencedImages) => {
 		lines.push(
 			'',
 			'Unreferenced Images',
-			'These files are kept under page or route image roots but are not referenced by Norna-managed image references:',
+			'These files are kept under page image roots but are not referenced by Norna-managed image references:',
 		);
 
 		for (const imagePath of unreferencedImages) {
@@ -171,16 +171,16 @@ const getAspectRatioLabel = ({ width, height }) => {
 	return `${width / divisor}:${height / divisor}`;
 };
 
-const getExpectedImagePath = (contentFile, sectionId, imageName) =>
-	path.join(contentFile.imagesDir, sectionId, imageName);
+const getExpectedImagePath = (contentFile, imageName) =>
+	path.join(contentFile.imagesDir, imageName);
 
-const getExpectedImageLabel = (contentFile, sectionId, imageName) =>
-	`${contentFile.imagesLabel}/${sectionId}/${imageName}`;
+const getExpectedImageLabel = (contentFile, imageName) =>
+	`${contentFile.imagesLabel}/${imageName}`;
 
 const getGlobalImageCandidates = (globalImageCandidatesByName, imageName, expectedPath) =>
 	(globalImageCandidatesByName.get(imageName) ?? []).filter(({ imagePath }) => imagePath !== expectedPath);
 
-const getReferenceLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id}]`;
+const getReferenceLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id ?? 'page title'}]`;
 
 const getRootLabel = (contentFile) => contentFile.isHome
 	? contentFile.imagesLabel
@@ -217,8 +217,8 @@ const assertCleanGitForCrossRootSync = async (moves) => {
 	} catch (error) {
 		addIssue({
 			severity: 'error',
-			message: 'Cross-route content sync requires a clean git working tree, but git status could not be checked.',
-			fix: 'Run content:sync inside a Git worktree, or move cross-route image files manually.',
+			message: 'Cross-page content sync requires a clean git working tree, but git status could not be checked.',
+			fix: 'Run content:sync inside a Git worktree, or move cross-page image files manually.',
 		});
 		return;
 	}
@@ -227,7 +227,7 @@ const assertCleanGitForCrossRootSync = async (moves) => {
 
 	addIssue({
 		severity: 'error',
-		message: 'Cross-route content sync requires a clean git working tree before moving files between page or route image roots.',
+		message: 'Cross-page content sync requires a clean git working tree before moving files between page image roots.',
 		fix: `Commit or stash your current changes, then run content:sync again. Current changes:\n${stdout.trim()}`,
 	});
 };
@@ -256,9 +256,9 @@ const addConflictingMoveIssues = () => {
 		if (destinations.size <= 1) continue;
 
 		const firstMove = moves[0];
-		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
+		addSectionIssue(firstMove.contentFile, firstMove.section, {
 			severity: 'error',
-			message: `Cannot relocate "${firstMove.imageName}" because the same source file is referenced from multiple destinations: ${moves.map((move) => getExpectedImageLabel(move.contentFile, move.sectionId, move.imageName)).join(', ')}.`,
+			message: `Cannot relocate "${firstMove.imageName}" because the same source file is referenced from multiple destinations: ${moves.map((move) => getExpectedImageLabel(move.contentFile, move.imageName)).join(', ')}.`,
 			fix: 'Duplicate the image manually or rename one of the image files so each move has a single destination.',
 		});
 	}
@@ -268,9 +268,9 @@ const addConflictingMoveIssues = () => {
 		if (sources.size <= 1) continue;
 
 		const firstMove = moves[0];
-		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
+		addSectionIssue(firstMove.contentFile, firstMove.section, {
 			severity: 'error',
-			message: `Cannot relocate "${firstMove.imageName}" because multiple source files would move to ${getExpectedImageLabel(firstMove.contentFile, firstMove.sectionId, firstMove.imageName)}: ${moves.map((move) => getCandidateLabel(move.sourceContentFile ? { contentFile: move.sourceContentFile, imagePath: move.from } : move)).join(', ')}.`,
+			message: `Cannot relocate "${firstMove.imageName}" because multiple source files would move to ${getExpectedImageLabel(firstMove.contentFile, firstMove.imageName)}: ${moves.map((move) => getCandidateLabel(move.sourceContentFile ? { contentFile: move.sourceContentFile, imagePath: move.from } : move)).join(', ')}.`,
 			fix: 'Move the intended file manually or rename files so the destination is unambiguous.',
 		});
 	}
@@ -284,8 +284,8 @@ const validateImageReference = async (
 	expectedReferencesByPath,
 ) => {
 	const imageName = reference.image;
-	const expectedPath = getExpectedImagePath(contentFile, section.id, imageName);
-	const expectedLabel = getExpectedImageLabel(contentFile, section.id, imageName);
+	const expectedPath = getExpectedImagePath(contentFile, imageName);
+	const expectedLabel = getExpectedImageLabel(contentFile, imageName);
 	const expectedExists = await stat(expectedPath).then((entry) => entry.isFile()).catch(() => false);
 
 	if (expectedExists) {
@@ -297,8 +297,8 @@ const validateImageReference = async (
 	if (candidates.length === 0) {
 		addSectionIssue(contentFile, section, {
 			severity: 'error',
-			message: `Image "${imageName}" does not exist at ${expectedLabel} or anywhere under any page or route image root.`,
-			fix: `Add the source image to ${contentFile.imagesLabel}/${section.id}/ or remove the Norna-managed image reference.`,
+			message: `Image "${imageName}" does not exist at ${expectedLabel} or anywhere under any page image root.`,
+			fix: `Add the source image directly to ${contentFile.imagesLabel}/ or remove the Norna-managed image reference.`,
 		});
 		return null;
 	}
@@ -315,7 +315,7 @@ const validateImageReference = async (
 	const sourceCandidate = candidates[0];
 	const sourcePath = sourceCandidate.imagePath;
 	const referencesAtCurrentLocation = (expectedReferencesByPath.get(sourcePath) ?? [])
-		.filter((expectedReference) => expectedReference.contentFile !== contentFile || expectedReference.section.id !== section.id);
+		.filter((expectedReference) => expectedReference.contentFile !== contentFile);
 
 	if (referencesAtCurrentLocation.length > 0) {
 		addSectionIssue(contentFile, section, {
@@ -326,15 +326,17 @@ const validateImageReference = async (
 		return null;
 	}
 
-	imageMoves.push({
-		imageName,
-		from: sourcePath,
-		to: expectedPath,
-		contentFile,
-		sourceContentFile: sourceCandidate.contentFile,
-		sectionId: section.id,
-		crossRoot: sourceCandidate.contentFile !== contentFile,
-	});
+	if (!imageMoves.some((move) => move.from === sourcePath && move.to === expectedPath)) {
+		imageMoves.push({
+			imageName,
+			from: sourcePath,
+			to: expectedPath,
+			contentFile,
+			sourceContentFile: sourceCandidate.contentFile,
+			section,
+			crossRoot: sourceCandidate.contentFile !== contentFile,
+		});
+	}
 	referencedImagePaths.add(sourcePath);
 
 	if (!shouldWrite) {
@@ -342,8 +344,8 @@ const validateImageReference = async (
 			severity: 'error',
 			message: `Image "${imageName}" is used here but is located in ${getCandidateLabel(sourceCandidate)}.`,
 			fix: sourceCandidate.contentFile === contentFile
-				? 'Run norna content:sync to move it inside the current page or route image root.'
-				: `Run norna content:sync to move it from ${getRootLabel(sourceCandidate.contentFile)} to ${getRootLabel(contentFile)}. Cross-route sync requires a clean git working tree when files are moved.`,
+				? 'Run norna content:sync to move it directly into the current page image root.'
+				: `Run norna content:sync to move it from ${getRootLabel(sourceCandidate.contentFile)} to ${getRootLabel(contentFile)}. Cross-page sync requires a clean git working tree when files are moved.`,
 		});
 	}
 
@@ -412,11 +414,27 @@ for (const contentFile of contentFiles) {
 	validateFrontmatterIndentation(frontmatter, addIssue);
 	validateContentFrontmatterStructure(frontmatter, addIssue);
 
-	const frontmatterSections = getFrontmatterSections(frontmatter);
-	const frontmatterIds = new Set(frontmatterSections.map((section) => section.id));
-	const { sections } = getBodySections(body);
+	const { headings, pageHeadings, prelude, sections } = await getBodySections(body);
+	const headingIdentifierIssues = getHeadingIdentifierIssues(headings);
+	const invalidHeadingLines = new Set();
+	for (const issue of headingIdentifierIssues) {
+		invalidHeadingLines.add(issue.heading.line);
+		if (issue.otherHeading) invalidHeadingLines.add(issue.otherHeading.line);
+		const line = bodyLineOffset + issue.heading.line;
+		const relatedLine = issue.otherHeading
+			? ` The other heading is on line ${bodyLineOffset + issue.otherHeading.line}.`
+			: '';
+		addIssue({
+			severity: 'error',
+			message: `${contentFile.contentLabel} line ${line}: ${issue.message}${relatedLine}`,
+			fix: issue.fix,
+			sectionId: `${contentFile.contentLabel}:heading:${issue.heading.line}`,
+			sectionLabel: `${contentFile.contentLabel} line ${line}`,
+		});
+	}
 	const sectionsById = new Map();
-	const blockResultsBySectionId = new Map();
+	const blockResultsBySection = new Map();
+	const validSections = new Set();
 	const imageCandidatesByName = await getImageCandidatesByName(contentFile.imagesDir);
 
 	for (const [imageName, candidates] of imageCandidatesByName) {
@@ -427,36 +445,71 @@ for (const contentFile of contentFiles) {
 		}
 	}
 
+	if (pageHeadings.length === 0) {
+		addContentIssue(contentFile, {
+			severity: 'error',
+			message: 'The page is missing its Markdown H1 title.',
+			fix: 'Add exactly one page title before any sections, for example "# About".',
+		});
+	} else if (pageHeadings.length > 1) {
+		addContentIssue(contentFile, {
+			severity: 'error',
+			message: `The page contains ${pageHeadings.length} Markdown H1 headings.`,
+			fix: 'Keep exactly one H1 page title. Use level 2 headings with explicit ids for sections.',
+		});
+	}
+
+	if (sections[0] && !sections[0].isPageTitle) {
+		addContentIssue(contentFile, {
+			severity: 'error',
+			message: `The first content heading is "${sections[0].heading}", but a Norna page must start with its H1 title.`,
+			fix: 'Add the page title first, for example "# About".',
+		});
+	}
+
+	if (prelude.trim()) {
+		addContentIssue(contentFile, {
+			severity: 'error',
+			message: 'The page contains content before its first heading.',
+			fix: 'Make the Markdown H1 page title the first content after optional frontmatter.',
+		});
+	}
+
 	for (const section of sections) {
-		if (!section.id) {
-			addSectionIssue(contentFile, section, {
-				severity: 'error',
-				message: `Section heading "${section.heading.replace(/^##\s+/, '')}" is missing an explicit id.`,
-				fix: `Write it as: ${section.heading} {#section-id}`,
-			});
+		if (section.isPageTitle) {
+			if (
+				pageHeadings.length === 1
+				&& sections[0] === section
+				&& !invalidHeadingLines.has(section.line)
+			) {
+				validSections.add(section);
+			}
 			continue;
 		}
 
+		if (invalidHeadingLines.has(section.line) || !section.id) continue;
+
 		if (sectionsById.has(section.id)) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
-				message: `Duplicate Markdown section heading id "${section.id}".`,
-				fix: 'Each Markdown level 2 section heading must use a unique explicit id within the page.',
+				message: `Duplicate Markdown heading id "${section.id}".`,
+				fix: 'Add a unique explicit id to at least one heading.',
 			});
 			continue;
 		}
 
 		sectionsById.set(section.id, section);
+		validSections.add(section);
 	}
 
 	for (const section of sections) {
-		if (!section.id || !sectionsById.has(section.id)) continue;
+		if (!validSections.has(section)) continue;
 
 		const blockResults = extractNornaMarkdownBlockDiagnostics(section.text, {
 			label: contentFile.contentLabel,
 			lineOffset: bodyLineOffset + section.line - 1,
 		});
-		blockResultsBySectionId.set(section.id, blockResults);
+		blockResultsBySection.set(section, blockResults);
 
 		const inlineNoteResults = extractInlineNoteDiagnostics(section.text, {
 			label: contentFile.contentLabel,
@@ -470,17 +523,16 @@ for (const contentFile of contentFiles) {
 		}
 
 		for (const reference of getNornaBlockImageReferences(blockResults.blocks)) {
-			const expectedPath = getExpectedImagePath(contentFile, section.id, reference.image);
+			const expectedPath = getExpectedImagePath(contentFile, reference.image);
 			addExpectedReference(globalExpectedReferencesByPath, expectedPath, { contentFile, section, reference });
 		}
 	}
 
 	contentFileContexts.push({
 		contentFile,
-		frontmatterIds,
 		sections,
-		sectionsById,
-		blockResultsBySectionId,
+		validSections,
+		blockResultsBySection,
 		body,
 	});
 }
@@ -488,23 +540,12 @@ for (const contentFile of contentFiles) {
 for (const context of contentFileContexts) {
 	const {
 		contentFile,
-		frontmatterIds,
 		sections,
-		sectionsById,
-		blockResultsBySectionId,
+		validSections,
+		blockResultsBySection,
 		body,
 	} = context;
 
-	for (const id of frontmatterIds) {
-		if (!sectionsById.has(id)) {
-			addContentIssue(contentFile, {
-				severity: 'error',
-				message: `Section metadata "${id}" does not match any Markdown section.`,
-				fix: `Add a level 2 Markdown heading, for example "## Heading {#${id}}", or remove sections.${id}.`,
-			});
-		}
-	}
-
 	for (const styleName of new Set(getDeprecatedInlineStyleReferences(body))) {
 		addContentIssue(contentFile, {
 			severity: 'error',
@@ -514,7 +555,7 @@ for (const context of contentFileContexts) {
 	}
 
 	for (const section of sections) {
-		if (!section.id || !sectionsById.has(section.id)) continue;
+		if (!validSections.has(section)) continue;
 
 		const markdownImages = extractMarkdownImageReferences(section.text);
 		for (const reference of markdownImages) {
@@ -525,7 +566,7 @@ for (const context of contentFileContexts) {
 			});
 		}
 
-		const { blocks, errors: blockErrors } = blockResultsBySectionId.get(section.id) ?? { blocks: [], errors: [] };
+		const { blocks, errors: blockErrors } = blockResultsBySection.get(section) ?? { blocks: [], errors: [] };
 		for (const error of blockErrors) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
@@ -601,5 +642,5 @@ if (!canWrite) {
 for (const move of imageMoves) {
 	await mkdir(path.dirname(move.to), { recursive: true });
 	await rename(move.from, move.to);
-	console.log(`Moved image "${move.imageName}" to ${move.contentFile.imagesLabel}/${move.sectionId}/.`);
+	console.log(`Moved image "${move.imageName}" to ${move.contentFile.imagesLabel}/.`);
 }

package/scripts/{test-temporary-visibility.mjs → test-banner-visibility.mjs}

@@ -8,7 +8,7 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
 const nornaBin = path.join(repoRoot, 'bin', 'norna.mjs');
 const tempParent = path.join(repoRoot, 'node_modules', '.cache');
 await mkdir(tempParent, { recursive: true });
-const tempRoot = await mkdtemp(path.join(tempParent, 'norna-temporary-visibility-'));
+const tempRoot = await mkdtemp(path.join(tempParent, 'norna-banner-visibility-'));
 const siteDir = path.join(tempRoot, 'site');
 
 const runCli = (args, env = {}) => {
@@ -34,7 +34,7 @@ const runCli = (args, env = {}) => {
 };
 
 try {
-	await mkdir(path.join(siteDir, 'images', 'work'), { recursive: true });
+	await mkdir(path.join(siteDir, 'images'), { recursive: true });
 	await mkdir(path.join(siteDir, 'public'), { recursive: true });
 	await writeFile(path.join(siteDir, 'public', 'robots.txt'), 'User-agent: *\nAllow: /\n');
 	await writeFile(path.join(siteDir, 'config.yaml'), 'url: https://example.com/\n');
@@ -56,28 +56,13 @@ palette: dark
     text: Active banner text.
 `);
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Temporary Visibility Test
-description: Test site for temporary sections.
-sections:
-  expired:
-    visible:
-      until: "2026-01-01"
-  active:
-    visible:
-      from: "2026-01-01"
-      until: "2026-12-31"
-  always: {}
-
+page:
+  description: Test site for temporary banners.
 ---
-## Expired {#expired}
-
-Expired section text.
-
-## Active {#active}
 
-Active section text.
+# Temporary Visibility Test
 
-## Always {#always}
+## Content {#content}
 
 Always visible section text.
 `);
@@ -85,13 +70,11 @@ Always visible section text.
 	runCli(['build'], { NORNA_TODAY: '2026-06-15' });
 
 	const html = await readFile(path.join(tempRoot, 'dist', 'index.html'), 'utf8');
-	assert.match(html, /Active section text/);
 	assert.match(html, /Always visible section text/);
-	assert.doesNotMatch(html, /Expired section text/);
 	assert.match(html, /Active banner text/);
 	assert.doesNotMatch(html, /Expired banner text/);
 
-	console.log('Temporary visibility test passed.');
+	console.log('Temporary banner visibility test passed.');
 } finally {
 	await rm(tempRoot, { force: true, recursive: true });
 }

package/scripts/test-client-javascript.mjs

@@ -10,7 +10,7 @@ const tempParent = path.join(repoRoot, 'node_modules', '.cache');
 await mkdir(tempParent, { recursive: true });
 const tempRoot = await mkdtemp(path.join(tempParent, 'norna-client-javascript-'));
 const siteDir = path.join(tempRoot, 'site');
-const routeDir = path.join(siteDir, 'routes', '010-details');
+const pageDir = path.join(siteDir, 'pages', '010-details');
 const configPath = path.join(siteDir, 'config.yaml');
 
 const runBuild = () => {
@@ -59,17 +59,14 @@ try {
 	await writeFile(path.join(siteDir, 'theme.yaml'), `typography:
   profile: reading
 palette: paper
-`);
-	await writeFile(path.join(siteDir, 'sitewide-content.yaml'), `navigation:
-  label: Test site
 `);
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Section navigation
-description: A single page with sticky section navigation.
-sections:
-  intro: {}
-  more: {}
+page:
+  description: A single page with sticky section navigation.
 ---
+
+# Section navigation
+
 ## Intro {#intro}
 
 The section heading is a native anchor target.
@@ -104,27 +101,26 @@ The navigation enhancement keeps native anchors clear of the sticky header.
 
 	await writeConfig();
 
-	await mkdir(path.join(routeDir, 'images', 'details'), { recursive: true });
-	await writeSvg(path.join(routeDir, 'images', 'details', 'first.svg'), '#7b8f78');
-	await writeSvg(path.join(routeDir, 'images', 'details', 'second.svg'), '#a7664b');
+	await mkdir(path.join(pageDir, 'images'), { recursive: true });
+	await writeSvg(path.join(pageDir, 'images', 'first.svg'), '#7b8f78');
+	await writeSvg(path.join(pageDir, 'images', 'second.svg'), '#a7664b');
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Static baseline
-description: A page without interactive features.
-sections:
-  intro: {}
+page:
+  description: A page without interactive features.
 ---
+
+# Static baseline
+
 ## Intro {#intro}
 
 Ordinary Markdown needs no client-side JavaScript.
 `);
-	await writeFile(path.join(routeDir, 'content.md'), `---
-title: Details
-description: Static managed images.
-sections:
-  details: {}
+	await writeFile(path.join(pageDir, 'content.md'), `---
+page:
+  description: Static managed images.
 ---
-## Details {#details}
 
+# Details
 Static image stacks remain static.
 
 \`\`\`norna-image-stack
@@ -148,23 +144,25 @@ Static image stacks remain static.
 	);
 
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Notes
-description: A page with an enhanced sidenote.
-sections:
-  intro: {}
+page:
+  description: A page with an enhanced sidenote.
 ---
+
+# Notes
+
 ## Intro {#intro}
 
 This sentence has additional context.{note-ref}
 
 {note: The note remains readable without JavaScript, while alignment is enhanced when JavaScript runs.}
 `);
-	await writeFile(path.join(routeDir, 'content.md'), `---
-title: Carousel
-description: An interactive image carousel.
-sections:
-  details: {}
+	await writeFile(path.join(pageDir, 'content.md'), `---
+page:
+  description: An interactive image carousel.
 ---
+
+# Carousel
+
 ## Details {#details}
 
 \`\`\`norna-image-carousel
@@ -185,24 +183,23 @@ sections:
 	assert.match(getScripts(carouselHtml)[0], /\ssrc=/, 'Carousel JavaScript should be emitted as a module asset.');
 
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Banner
-description: A page with a dismissible banner.
-sections:
-  intro: {}
+page:
+  description: A page with a dismissible banner.
 ---
+
+# Banner
+
 ## Intro {#intro}
 
 The only interactive feature is the banner.
 `);
-	await writeFile(path.join(routeDir, 'content.md'), `---
-title: Details
-description: A second plain page.
-sections:
-  details: {}
+	await writeFile(path.join(pageDir, 'content.md'), `---
+page:
+  description: A second plain page.
 ---
-## Details {#details}
 
-Plain route content.
+# Details
+Plain page content.
 `);
 	await writeFile(path.join(siteDir, 'sitewide-content.yaml'), `banners:
   - id: test-banner