@janga/norna 0.7.17 → 0.7.22

package/scripts/lib/schema-editor-metadata.mjs

@@ -1,4 +1,5 @@
 import { documentationLink } from './documentation-links.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { getSchemaValueDefinition } from './schema-value-definitions.mjs';
 
 const yamlExample = (source) => `\`\`\`yaml\n${source}\n\`\`\``;
@@ -121,7 +122,7 @@ const addSitewideLogoHelp = (jsonSchema) => {
 
 	logo.markdownDescription = [
 		yamlExample('logo:\n  height: 2rem'),
-		'`logo` optionally overrides the displayed height of the convention-based logo file. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
+		'`logo` optionally overrides the displayed height of the convention-based logo file. Without an override, Norna uses 2.6rem on wider screens and caps the logo at 2.15rem on narrow screens. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
 		documentationLink('Navigation logo filenames and placement', 'public-files.md', 'navigation-logo'),
 	].join('\n\n');
 	logo.properties.height.examples = ['2rem'];
@@ -151,6 +152,27 @@ const addConfigHelp = (jsonSchema) => {
 		'Sets the page language and selects Norna\'s built-in English or Swedish interface text. The default is `en`.',
 		documentationLink('Language reference', 'configuration.md', 'language'),
 	], ['en', 'sv', 'en-GB', 'sv-SE']);
+	addHelp(jsonSchema, 'navigation', [
+		yamlExample('navigation:\n  mode: automatic'),
+		'Sets one navigation model for the complete site. `automatic` selects from the page hierarchy.',
+		documentationLink('Navigation reference', 'pages.md', 'navigation'),
+	]);
+	addFieldHelp(
+		jsonSchema,
+		'navigation.mode',
+		'navigation:\n  mode: automatic',
+		'pages.md',
+		'navigation',
+		['automatic', 'sections', 'top', 'tree'],
+	);
+	addFieldHelp(
+		jsonSchema,
+		'navigation.sectionTracking',
+		'navigation:\n  sectionTracking: true',
+		'configuration.md',
+		'navigationsectiontracking',
+		[true, false],
+	);
 	addHelp(jsonSchema, 'scrollBehavior', [
 		yamlExample('scrollBehavior: smooth'),
 		'Controls same-page anchor movement. `instant` is the default; `smooth` uses the browser\'s native smooth scrolling.',
@@ -166,25 +188,17 @@ const addThemeHelp = (jsonSchema) => {
 	].join('\n\n');
 	addHelp(jsonSchema, 'preset', [
 		yamlExample('preset: documentation'),
-		'Selects coordinated navigation, layout, image sizing, typography, palette and section surfaces. This is the normal starting point for a theme.',
+		'Selects coordinated corners, layout, image sizing, content-block defaults, typography, palette and section backgrounds. This is the normal starting point for a theme.',
 		documentationLink('Compare theme presets', 'theme.md', 'theme-presets'),
 	]);
-	addHelp(jsonSchema, 'navigation', [
-		yamlExample('navigation:\n  mode: automatic'),
-		'Sets the site-wide navigation model. Only the root theme may override this preset value.',
-		documentationLink('Theme reference', 'theme.md'),
-	]);
-	addFieldHelp(
-		jsonSchema,
-		'navigation.mode',
-		'navigation:\n  mode: automatic',
-		'theme.md',
-		undefined,
-		['automatic', 'sections', 'top', 'tree'],
-	);
+	addHelp(jsonSchema, 'corners', [
+		yamlExample('corners: rounded'),
+		'Chooses one consistent corner treatment for navigation, cards and framed content throughout the site.',
+		documentationLink('Corner reference', 'theme.md', 'corners'),
+	], ['square', 'rounded']);
 	addHelp(jsonSchema, 'layout', [
-		yamlExample('layout:\n  density: compact\n  pageWidth: 72rem'),
-		'Overrides page width, gutters and structural spacing after the selected preset.',
+		yamlExample('layout:\n  contentSpacing: compact\n  textWidth: narrow'),
+		'Overrides text width, content spacing, page width and gutters after the selected preset.',
 		documentationLink('Layout reference', 'theme.md', 'layout'),
 	]);
 	addHelp(jsonSchema, 'images', [
@@ -192,24 +206,92 @@ const addThemeHelp = (jsonSchema) => {
 		'Overrides the available width and height used by Norna-managed images.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
+	addHelp(jsonSchema, 'blocks', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Overrides preset defaults for structured Norna content blocks throughout the site. Options written directly in a Markdown block take priority.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addHelp(jsonSchema, 'blocks.cardList', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Sets site-wide defaults for card lists. A `width` option in an individual `norna-card-list` block overrides this setting.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addFieldHelp(
+		jsonSchema,
+		'blocks.cardList.width',
+		'blocks:\n  cardList:\n    width: text',
+		'theme.md',
+		'content-block-defaults',
+		['text', 'narrow', 'normal', 'wide'],
+	);
+	addSnippets(jsonSchema, 'blocks', [schemaSnippet({
+		label: 'Override content-block defaults',
+		body: {
+			cardList: {
+				width: '${1:text}',
+			},
+		},
+		description: 'Override a preset default for structured content blocks across the site.',
+		file: 'theme.md',
+		anchor: 'content-block-defaults',
+	})]);
 	addHelp(jsonSchema, 'typography', [
 		yamlExample('typography:\n  profile: reading\n  rhythm: normal'),
 		'Overrides the preset\'s font stack, typography profile, rhythm or individual text settings.',
 		documentationLink('Typography configuration reference', 'typography.md', 'configuration-shape'),
 	]);
 	addHelp(jsonSchema, 'palette', [
-		yamlExample('palette: paper'),
-		'Chooses a coordinated color system for the page frame, navigation, footer and section surfaces.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
-	], ['dark', 'light', 'paper']);
-	addHelp(jsonSchema, 'sectionSurfaces', [
-		yamlExample('sectionSurfaces: [base, soft, emphasis]'),
-		'Lists one to three semantic surfaces. Norna cycles through them in section order; omit this field to keep the preset sequence.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
-	], [['base'], ['base', 'soft'], ['base', 'soft', 'emphasis']]);
+		yamlExample('palette: warm-paper'),
+		'Chooses the site color character. Every palette provides coordinated light and dark variants.',
+		documentationLink('Palette and color mode', 'theme.md', 'palette-and-color-mode'),
+	], presentationPaletteNames);
+	addHelp(jsonSchema, 'colorMode', [
+		yamlExample('colorMode:\n  default: system'),
+		'Controls the initial light or dark appearance. Enable the reader-facing choice under readerControls.',
+		documentationLink('Color mode', 'theme.md', 'color-mode'),
+	]);
+	addFieldHelp(jsonSchema, 'colorMode.default', 'colorMode:\n  default: system', 'theme.md', 'color-mode', ['system', 'light', 'dark']);
+	addSnippets(jsonSchema, 'colorMode', [schemaSnippet({
+		label: 'Set the initial color mode',
+		body: 'colorMode:\n  default: ${1:system}',
+		description: 'Follow the system color preference or choose a fixed initial appearance.',
+		file: 'theme.md',
+		anchor: 'color-mode',
+	})]);
+	addHelp(jsonSchema, 'readerControls', [
+		yamlExample('readerControls:\n  colorMode: true\n  focusReading: true'),
+		'Adds optional color-mode and focus-reading choices to the site-wide Display panel. Reading width is always available, and tree navigation always provides Focus reading.',
+		documentationLink('Reader Display controls', 'theme.md', 'reader-display-controls'),
+	]);
+	for (const [propertyPath, example] of [
+		['readerControls.colorMode', 'readerControls:\n  colorMode: true'],
+		['readerControls.focusReading', 'readerControls:\n  focusReading: true'],
+	]) {
+		addFieldHelp(
+			jsonSchema,
+			propertyPath,
+			example,
+			'theme.md',
+			'reader-display-controls',
+		);
+	}
+	addSnippets(jsonSchema, 'readerControls', [schemaSnippet({
+		label: 'Configure the Display panel',
+		body: 'readerControls:\n  colorMode: ${1:true}\n  focusReading: ${2:true}',
+		description: 'Offer optional color-mode and focus-reading choices alongside the universal reading-width control. Tree navigation always provides Focus reading.',
+		file: 'theme.md',
+		anchor: 'reader-display-controls',
+	})]);
+	addHelp(jsonSchema, 'sections', [
+		yamlExample('sections:\n  backgroundPattern: alternating'),
+		'Chooses whether H2 section backgrounds stay uniform, alternate between two backgrounds or move from base to soft to emphasis and back through soft. Non-uniform patterns are available with sections and top navigation; tree navigation requires uniform.',
+		documentationLink('Section backgrounds', 'theme.md', 'section-backgrounds'),
+	]);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'section-backgrounds', ['uniform', 'alternating', 'accented']);
 
 	const layoutFields = [
-		['layout.density', 'layout:\n  density: compact'],
+		['layout.contentSpacing', 'layout:\n  contentSpacing: compact'],
+		['layout.textWidth', 'layout:\n  textWidth: narrow'],
 		['layout.pageWidth', 'layout:\n  pageWidth: 72rem'],
 		['layout.gutter', 'layout:\n  gutter:\n    desktop: clamp(1.25rem, 4vw, 3rem)\n    mobile: 1rem'],
 		['layout.gutter.desktop', 'layout:\n  gutter:\n    desktop: clamp(1.25rem, 4vw, 3rem)'],
@@ -301,9 +383,9 @@ const addThemeHelp = (jsonSchema) => {
 		['typography.fontFamily', 'typography:\n  fontFamily: "Arial, sans-serif"'],
 		['typography.profile', 'typography:\n  profile: reading'],
 		['typography.rhythm', 'typography:\n  rhythm: normal'],
-		['typography.overrides', 'typography:\n  overrides:\n    body:\n      width: narrow'],
+		['typography.overrides', 'typography:\n  overrides:\n    body:\n      lineHeight: 1.55'],
 		['typography.overrides.headings', 'typography:\n  overrides:\n    headings:\n      h2:\n        size: medium'],
-		['typography.overrides.body', 'typography:\n  overrides:\n    body:\n      width: narrow'],
+		['typography.overrides.body', 'typography:\n  overrides:\n    body:\n      lineHeight: 1.55'],
 		['typography.overrides.caption', 'typography:\n  overrides:\n    caption:\n      size: small'],
 	];
 	for (const [propertyPath, example] of typographyFields) {
@@ -346,7 +428,6 @@ const addThemeHelp = (jsonSchema) => {
 		textOverrideHelp(propertyPath, `${prefix}\n      `, true);
 	}
 	textOverrideHelp('typography.overrides.body', 'typography:\n  overrides:\n    body:');
-	addFieldHelp(jsonSchema, 'typography.overrides.body.width', 'typography:\n  overrides:\n    body:\n      width: narrow', 'typography.md', 'configuration-shape');
 	addFieldHelp(jsonSchema, 'typography.overrides.body.paragraphSpacing', 'typography:\n  overrides:\n    body:\n      paragraphSpacing: 1em', 'typography.md', 'configuration-shape');
 	textOverrideHelp('typography.overrides.caption', 'typography:\n  overrides:\n    caption:');
 	addFieldHelp(jsonSchema, 'typography.overrides.caption.spacingBefore', 'typography:\n  overrides:\n    caption:\n      spacingBefore: 0.5em', 'typography.md', 'configuration-shape');
@@ -359,9 +440,8 @@ const addThemeHelp = (jsonSchema) => {
 					weight: '${2:600}',
 				},
 			},
-			body: {
-				width: '${3:narrow}',
-				lineHeight: '${4:1.55}',
+		body: {
+				lineHeight: '${3:1.55}',
 			},
 		},
 		description: 'Start a focused set of heading and body-text overrides.',
@@ -370,6 +450,44 @@ const addThemeHelp = (jsonSchema) => {
 	})]);
 };
 
+const addPageThemeHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
+		'A limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.',
+		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'layout', [
+		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
+		'Adjusts body-text line length and vertical content spacing for pages below this directory.',
+		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
+	]);
+	addFieldHelp(jsonSchema, 'layout.textWidth', 'layout:\n  textWidth: narrow', 'theme.md', 'page-themes', ['narrow', 'normal', 'wide']);
+	addFieldHelp(jsonSchema, 'layout.contentSpacing', 'layout:\n  contentSpacing: compact', 'theme.md', 'page-themes', ['compact', 'normal', 'spacious']);
+	addHelp(jsonSchema, 'images', [
+		yamlExample('images:\n  width: 900px'),
+		'Adjusts managed-image sizing for pages below this directory.',
+		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
+	]);
+	const imageFields = [
+		['images.width', 'images:\n  width: 900px'],
+		['images.maxAvailableWidthPercent', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100\n    mobile: 100'],
+		['images.maxAvailableWidthPercent.desktop', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100'],
+		['images.maxAvailableWidthPercent.mobile', 'images:\n  maxAvailableWidthPercent:\n    mobile: 100'],
+		['images.maxAvailableHeightPercent', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68'],
+		['images.maxAvailableHeightPercent.desktop', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74'],
+		['images.maxAvailableHeightPercent.mobile', 'images:\n  maxAvailableHeightPercent:\n    mobile: 68'],
+	];
+	for (const [propertyPath, example] of imageFields) {
+		addFieldHelp(jsonSchema, propertyPath, example, 'theme.md', 'image-sizing');
+	}
+	addHelp(jsonSchema, 'sections', [
+		yamlExample('sections:\n  backgroundPattern: alternating'),
+		'Adjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.',
+		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
+	]);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'accented']);
+};
+
 const addSitewideHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('footer:\n  copyrightMessage: Copyright Example Owner.'),
@@ -462,13 +580,28 @@ const addContentHelp = (jsonSchema) => {
 	addFieldHelp(jsonSchema, 'navigation.listed', 'navigation:\n  listed: false', 'pages.md', 'navigation', [true, false]);
 };
 
+const addCategoryHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('label: Guides'),
+		'`category.yaml` creates a navigation-only group for child pages. It has no page content and produces no URL of its own.',
+		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'label', [
+		yamlExample('label: Guides'),
+		'The category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.',
+		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
+	]);
+};
+
 export const applySchemaEditorMetadata = (filename, jsonSchema) => {
 	addValueDescriptions(jsonSchema);
+	if (filename === 'category.schema.json') addCategoryHelp(jsonSchema);
 	if (filename === 'config.schema.json') {
 		addLanguageSuggestions(jsonSchema);
 		addConfigHelp(jsonSchema);
 	}
 	if (filename === 'theme.schema.json') addThemeHelp(jsonSchema);
+	if (filename === 'page-theme.schema.json') addPageThemeHelp(jsonSchema);
 	if (filename === 'sitewide-content.schema.json') addSitewideHelp(jsonSchema);
 	if (filename === 'content-frontmatter.schema.json') addContentHelp(jsonSchema);
 	return jsonSchema;

package/scripts/lib/schema-value-definitions.mjs

@@ -2,6 +2,10 @@ import {
 	getThemePresetMetadata,
 	themePresetNames,
 } from './theme-presets.mjs';
+import {
+	getPresentationPaletteMetadata,
+	presentationPaletteNames,
+} from './presentation-palette-metadata.mjs';
 
 const option = (title, description) => Object.freeze({ title, description });
 const definition = (values, options) => Object.freeze({
@@ -44,6 +48,12 @@ export const schemaValueDefinitions = Object.freeze([
 		normal: option('Normal', 'Use the balanced default line length.'),
 		wide: option('Wide', 'Allow body text to use more horizontal space.'),
 	}),
+	definition(['text', 'narrow', 'normal', 'wide'], {
+		text: option('Text width', 'Match the active body-text width, including a reader-selected reading width.'),
+		narrow: option('Narrow', 'Limit the complete card list to at most 48rem.'),
+		normal: option('Normal', 'Limit the complete card list to at most 56rem.'),
+		wide: option('Wide', 'Allow the complete card list to use the available page-layout width.'),
+	}),
 	definition([400, 500, 600, 700], {
 		400: option('Regular', 'Use regular font weight.'),
 		500: option('Medium', 'Use medium font weight.'),
@@ -56,10 +66,28 @@ export const schemaValueDefinitions = Object.freeze([
 		reading: option('Reading', 'Reading-focused typography with narrower text and relaxed line height.'),
 		statement: option('Statement', 'Stronger headings and tighter body rhythm for short, expressive pages.'),
 	}),
-	definition(['dark', 'light', 'paper'], {
-		dark: option('Dark', 'Black page and section surfaces with light text.'),
-		light: option('Light', 'White and cool light surfaces with dark text.'),
-		paper: option('Paper', 'Warm off-white surfaces with dark text.'),
+	definition(presentationPaletteNames, Object.fromEntries(presentationPaletteNames.map((name) => {
+		const metadata = getPresentationPaletteMetadata(name);
+		return [name, option(metadata.title, `${metadata.description} Includes coordinated light and dark variants.`)];
+	}))),
+	definition(['system', 'light', 'dark'], {
+		system: option('System', 'Follow the visitor\'s operating-system light or dark preference.'),
+		light: option('Light', 'Start with the palette\'s light appearance.'),
+		dark: option('Dark', 'Start with the palette\'s dark appearance.'),
+	}),
+	definition(['square', 'rounded'], {
+		square: option('Square', 'Use square corners for navigation, cards and framed content.'),
+		rounded: option('Rounded', 'Use restrained rounded corners consistently across the site.'),
+	}),
+	definition(['uniform', 'alternating', 'accented'], {
+		uniform: option('Uniform', 'Use the normal page background for every H2 section. Tree navigation requires this pattern.'),
+		alternating: option('Alternating', 'Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation.'),
+		accented: option('Accented', 'Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation.'),
+	}),
+	definition(['compact', 'normal', 'spacious'], {
+		compact: option('Compact', 'Use restrained spacing between sections and structured blocks.'),
+		normal: option('Normal', 'Use balanced content spacing.'),
+		spacious: option('Spacious', 'Use more expansive spacing between sections and structured blocks.'),
 	}),
 	definition(['base', 'soft', 'emphasis'], {
 		base: option('Base', 'Use the palette\'s normal page surface.'),

package/scripts/lib/site-content.mjs

@@ -1,19 +1,13 @@
-import { access, readdir, readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	siteContentLabel,
-	siteContentPath,
-	siteDir,
-	siteDirLabel,
-	siteImagesDir,
-	siteImagesLabel,
-	sitePagesDir,
-	sitePagesLabel,
 	sitewideContentLabel,
 } from './site-paths.mjs';
-import { parsePageDirectoryPath } from './page-model.mjs';
-import { getMarkdownHeadings } from './heading-ids.mjs';
 import { schemaTopLevelKeys } from './schema-definitions.mjs';
+import { getIndentInfo, validateYamlIndentation } from './yaml-indentation.mjs';
+
+export { getContentFiles } from './site-structure.mjs';
 
 export const rasterImageExtensions = new Set(['.jpg', '.jpeg', '.png']);
 export const staticImageExtensions = new Set(['.svg']);
@@ -25,7 +19,7 @@ const knownConfigTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.config);
 const knownContentTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.content);
 const knownThemeTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.theme);
 const knownPageThemeTopLevelFrontmatterKeys = new Set(
-	[...knownThemeTopLevelFrontmatterKeys].filter((key) => key !== 'navigation'),
+	schemaTopLevelKeys.pageTheme,
 );
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
@@ -34,9 +28,11 @@ const knownNestedFrontmatterKeys = new Set([
 	'body',
 	'blockGap',
 	'caption',
+	'colorMode',
 	'carousel',
-	'density',
+	'contentSpacing',
 	'desktop',
+	'default',
 	'fontFamily',
 	'from',
 	'finalSectionBottom',
@@ -65,13 +61,19 @@ const knownNestedFrontmatterKeys = new Set([
 	'palette',
 	'preset',
 	'profile',
+	'readerControls',
+	'readingWidth',
 	'rhythm',
 	'sectionGap',
-	'sectionSurfaces',
+	'backgroundPattern',
+	'sections',
+	'corners',
+	'focusReading',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
 	'theme',
+	'textWidth',
 	'typography',
 	'until',
 	'visible',
@@ -80,87 +82,6 @@ const knownNestedFrontmatterKeys = new Set([
 
 export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
-const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
-
-export const getContentFiles = async () => {
-	const legacyRoutesDir = path.join(siteDir, 'routes');
-	const legacyRoutes = await readdir(legacyRoutesDir).catch((error) => {
-		if (error?.code === 'ENOENT') return null;
-		throw error;
-	});
-	if (legacyRoutes !== null) {
-		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
-	}
-
-	const contentFiles = [{
-		contentLabel: siteContentLabel,
-		contentPath: siteContentPath,
-		imagesDir: siteImagesDir,
-		imagesLabel: siteImagesLabel,
-		isHome: true,
-		pageDirectory: null,
-		pageDirectories: [],
-		pageId: null,
-		pageIds: [],
-		pageOrder: 0,
-		pageOrders: [],
-		pagePath: '',
-		parentPagePath: null,
-		depth: 0,
-	}];
-	const collectPageContentFiles = async (pagesDir, pagesLabel, parentPageDirectory = '') => {
-		const pageEntries = await readdir(pagesDir, { withFileTypes: true }).catch((error) => {
-		if (error?.code === 'ENOENT') {
-			return [];
-		}
-
-		throw error;
-		});
-
-		for (const entry of pageEntries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
-			if (!entry.isDirectory()) continue;
-
-			const pageDirectory = parentPageDirectory
-				? `${parentPageDirectory}/pages/${entry.name}`
-				: entry.name;
-			const pageLabel = `${pagesLabel}/${entry.name}`;
-			const pageDir = path.join(pagesDir, entry.name);
-			const pageContentPath = path.join(pageDir, 'content.md');
-
-			if (!(await fileExists(pageContentPath))) {
-				const childPageEntries = await readdir(path.join(pageDir, 'pages'), { withFileTypes: true }).catch((error) => {
-					if (error?.code === 'ENOENT') return [];
-					throw error;
-				});
-				if (childPageEntries.some((childEntry) => childEntry.isDirectory())) {
-					throw new Error(`${pageLabel} contains nested pages but has no content.md of its own.`);
-				}
-				continue;
-			}
-			const pageMetadata = parsePageDirectoryPath(pageDirectory, pageLabel);
-
-			contentFiles.push({
-				contentLabel: `${pageLabel}/content.md`,
-				contentPath: pageContentPath,
-				imagesDir: path.join(pageDir, 'images'),
-				imagesLabel: `${pageLabel}/images`,
-				isHome: false,
-				...pageMetadata,
-			});
-
-			await collectPageContentFiles(
-				path.join(pageDir, 'pages'),
-				`${pageLabel}/pages`,
-				pageDirectory,
-			);
-		}
-	};
-
-	await collectPageContentFiles(sitePagesDir, sitePagesLabel);
-
-	return contentFiles;
-};
-
 export const splitSiteFile = (source, label = siteContentLabel) => {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
 
@@ -185,89 +106,12 @@ export const splitSiteFile = (source, label = siteContentLabel) => {
 
 export const readSiteFile = async (sitePath, label = siteContentLabel) => splitSiteFile(await readFile(sitePath, 'utf8'), label);
 
-const getIndentInfo = (line) => {
-	const characters = Array.from(line);
-	const indentCharacters = [];
-
-	for (const character of characters) {
-		if (character === ' ' || character === '\t' || character === '\u00a0' || character === '\uFFFD' || character === '\u00c2') {
-			indentCharacters.push(character);
-			continue;
-		}
-
-		break;
-	}
-
-	return {
-		indent: indentCharacters.length,
-		hasInvalidWhitespace: indentCharacters.some((character) => character !== ' '),
-	};
-};
-
-const getNextFrontmatterEntry = (lines, startIndex) => {
-	for (let index = startIndex + 1; index < lines.length; index += 1) {
-		const line = lines[index];
-		if (!line.trim() || line.trim().startsWith('#') || frontmatterDelimiterRegex.test(line)) {
-			continue;
-		}
-
-		return {
-			index,
-			line,
-			...getIndentInfo(line),
-		};
-	}
-
-	return null;
-};
-
 export const validateFrontmatterIndentation = (frontmatter, addIssue) => {
-	const lines = frontmatter.split(/\r?\n/);
-
-	for (const [index, line] of lines.entries()) {
-		const lineNumber = index + 1;
-		const trimmed = line.trim();
-
-		if (!trimmed || trimmed.startsWith('#') || frontmatterDelimiterRegex.test(line)) {
-			continue;
-		}
-
-		const { indent, hasInvalidWhitespace } = getIndentInfo(line);
-
-		if (hasInvalidWhitespace) {
-			addIssue({
-				severity: 'error',
-				message: `Frontmatter line ${lineNumber} uses tabs, non-breaking spaces, or invalid whitespace for indentation.`,
-				fix: 'Replace the indentation on that line with ordinary spaces.',
-			});
-			continue;
-		}
-
-		if (indent % 2 !== 0) {
-			addIssue({
-				severity: 'error',
-				message: `Frontmatter line ${lineNumber} is indented with ${indent} spaces.`,
-				fix: 'Use 2-space indentation levels in frontmatter.',
-			});
-		}
-
-		const keyValueMatch = line.match(/^(\s*)[A-Za-z][A-Za-z0-9-]*:\s+(.+)$/);
-		if (!keyValueMatch) continue;
-
-		const value = keyValueMatch[2].trim();
-		if (value === '|' || value === '>' || value.startsWith('|') || value.startsWith('>')) {
-			continue;
-		}
-
-		const nextEntry = getNextFrontmatterEntry(lines, index);
-		if (!nextEntry || nextEntry.indent <= indent) continue;
-
-		addIssue({
-			severity: 'error',
-			message: `Frontmatter line ${nextEntry.index + 1} is indented under line ${lineNumber}, but line ${lineNumber} already has a value.`,
-			fix: 'Move the later line to the same indentation level as its sibling, or place it under a key that has no value.',
-		});
-	}
+	validateYamlIndentation(frontmatter, (issue) => addIssue({
+		...issue,
+		message: issue.message.replace(/^YAML/, 'Frontmatter'),
+		fix: issue.fix.replace(/YAML/g, 'frontmatter'),
+	}));
 };
 
 export const validateFrontmatterStructure = (frontmatter, addIssue, {
@@ -303,9 +147,19 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 			fix = 'Put local image references in norna-image-stack or norna-image-carousel blocks in the Markdown body.';
 		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
 			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
-		} else if (fileKind === 'page theme' && key === 'navigation') {
-			message = `Frontmatter line ${lineNumber}: page themes may not define navigation.`;
-			fix = 'Set the site-wide navigation mode under "navigation:" in the root theme.yaml.';
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
+			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
+			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'shape') {
+			message = fileKind === 'page theme'
+				? `Frontmatter line ${lineNumber}: "shape" was replaced by the site-wide "corners" setting, which page themes cannot override.`
+				: `Frontmatter line ${lineNumber}: "shape" was replaced by "corners". Use "square" or replace the old "soft" value with "rounded".`;
+			fix = fileKind === 'page theme'
+				? 'Remove "shape:" from this page theme. Set "corners: square" or "corners: rounded" in the root theme.yaml when an override is needed.'
+				: 'Replace "shape:" with "corners:". Use "square" or replace the old "soft" value with "rounded".';
+		} else if (fileKind === 'page theme' && ['preset', 'corners', 'palette', 'typography'].includes(key)) {
+			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
+			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: ${fileKind} may not define navigation logo settings. Optional logo display settings belong under "logo:" in ${sitewideContentLabel}.`;
 			fix = `Move only the logo display settings under "logo:" in ${sitewideContentLabel}; the homepage Markdown H1 supplies navigation text and logo alternative text.`;
@@ -364,31 +218,6 @@ export const readThemeFile = async (sitePath) => {
 export const getDeprecatedInlineStyleReferences = (body) => Array.from(body.matchAll(deprecatedInlineStyleReferenceRegex))
 	.map((match) => match[1]);
 
-export const getBodySections = async (body) => {
-	const { headings, source } = await getMarkdownHeadings(body);
-	const structuralHeadings = headings.filter((heading) => heading.depth <= 2);
-	const prelude = structuralHeadings.length > 0 ? source.slice(0, structuralHeadings[0].index) : source;
-	const sections = structuralHeadings.map((heading, index) => {
-		const next = structuralHeadings[index + 1];
-		const end = next?.index ?? source.length;
-
-		return {
-			...heading,
-			heading: heading.source,
-			isPageTitle: heading.depth === 1,
-			level: heading.depth,
-			text: source.slice(heading.index, end).trimEnd(),
-		};
-	});
-
-	return {
-		headings,
-		pageHeadings: sections.filter((section) => section.isPageTitle),
-		prelude,
-		sections,
-	};
-};
-
 export const getImageFiles = async (directory) => {
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') {
@@ -412,25 +241,6 @@ export const getImageFiles = async (directory) => {
 	return files;
 };
 
-export const getImageIndex = async (contentDir, fail, contentLabel = siteImagesLabel) => {
-	const imageFiles = await getImageFiles(contentDir);
-	const imagesByName = new Map();
-
-	for (const imagePath of imageFiles) {
-		const imageName = path.basename(imagePath);
-		const existingPath = imagesByName.get(imageName);
-
-		if (existingPath) {
-			fail(`Duplicate image filename "${imageName}" found at ${contentLabel}/${toPosixPath(path.relative(contentDir, existingPath))} and ${contentLabel}/${toPosixPath(path.relative(contentDir, imagePath))}. The filename is ambiguous within this page image root.`);
-			continue;
-		}
-
-		imagesByName.set(imageName, imagePath);
-	}
-
-	return imagesByName;
-};
-
 export const getImageCandidatesByName = async (contentDir) => {
 	const imageFiles = await getImageFiles(contentDir);
 	const imagesByName = new Map();