@janga/norna 0.7.23 → 0.7.24

package/scripts/lib/presentation.mjs

@@ -44,7 +44,6 @@ const createPaletteMode = ({ appearance, page, surfaces, frame, css }) => {
 
 const presentationPalettes = Object.freeze({
 	'near-monochrome': Object.freeze({
-		defaultAppearance: 'dark',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -85,7 +84,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'arctic-blue': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -126,7 +124,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'mineral-teal': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -167,7 +164,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'soft-lavender': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -208,7 +204,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'warm-paper': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -249,7 +244,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'retro-earth': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -290,7 +284,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'clay-rose': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -331,7 +324,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'forest-moss': Object.freeze({
-		defaultAppearance: 'light',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -372,7 +364,6 @@ const presentationPalettes = Object.freeze({
 		}),
 	}),
 	'vivid-night': Object.freeze({
-		defaultAppearance: 'dark',
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
@@ -477,7 +468,7 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const palette = getPresentationPalette(paletteName);
 	const appearance = normalizedTheme.appearance ?? {};
 	const readerControls = normalizedTheme.readerControls ?? {};
-	const defaultAppearance = appearance.default ?? palette.defaultAppearance;
+	const defaultAppearance = appearance.default ?? 'system';
 	if (!appearanceNames.includes(defaultAppearance)) {
 		throw new Error(`appearance.default must be one of ${appearanceNames.join(', ')} in ${sourceLabel}.`);
 	}

package/scripts/lib/project-config.mjs

@@ -2,13 +2,18 @@ import { readFile } from 'node:fs/promises';
 import {
 	validateConfigYamlStructure,
 } from './site-content.mjs';
-import { defaultImagePresentation, imagePresentationNames } from './image-presentation.mjs';
+import {
+	defaultImageMaxAvailableHeightPercent,
+	defaultImagePresentation,
+	imagePresentationNames,
+} from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import {
 	siteConfigLabel,
 	siteConfigPath,
 	siteThemeLabel,
 } from './site-paths.mjs';
+import { normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
@@ -52,6 +57,16 @@ const readEnum = (object, key, path, allowedValues, fallback, sourceLabel = site
 	return value;
 };
 
+const readBoolean = (object, key, path, fallback, sourceLabel = siteConfigLabel) => {
+	const value = object[key] ?? fallback;
+
+	if (typeof value !== 'boolean') {
+		throw new Error(`${path}.${key} must be true or false in ${sourceLabel}.`);
+	}
+
+	return value;
+};
+
 const readFontFamily = (object, key, path, fallback, sourceLabel = siteConfigLabel) => {
 	const value = object[key] ?? fallback;
 
@@ -192,8 +207,17 @@ const localeLabels = Object.freeze({
 		codeCopied: 'Copied',
 		codeCopyFailed: 'Could not copy code',
 		copyCode: 'Copy code',
+		calloutCaution: 'Caution',
+		calloutDanger: 'Danger',
+		calloutImportant: 'Important',
+		calloutNote: 'Note',
+		calloutTip: 'Tip',
+		calloutWarning: 'Warning',
+		editSource: 'Edit this page',
 		displaySettings: 'Display',
 		focusReading: 'Focus reading',
+		footnoteBackReference: 'Back to reference {reference}',
+		footnotes: 'Footnotes',
 		readingWidth: 'Reading width',
 		readingWidthNarrow: 'Narrow',
 		readingWidthStandard: 'Standard',
@@ -203,14 +227,36 @@ const localeLabels = Object.freeze({
 		built: 'Built',
 		images: 'Images',
 		imageCarousel: 'image carousel',
+		navigationCollapsedAll: 'All navigation items collapsed.',
+		navigationCollapseAll: 'Collapse all',
+		navigationControls: 'Navigation tree controls',
 		navigationChildren: 'Child pages',
+		navigationExpandedAll: 'All navigation items expanded.',
+		navigationExpandAll: 'Expand all',
+		navigationFilter: 'Filter pages and groups',
+		navigationFilterEmpty: 'No matching pages or groups. The current page remains available.',
+		navigationFilterMatches: 'Matching navigation items: {count}',
+		navigationLocatedCurrent: 'Current page located.',
+		navigationLocateCurrent: 'Locate current page',
 		navigationMenu: 'Menu',
 		nextImage: 'Next image',
+		nextPage: 'Next page',
 		note: 'Note',
+		notFound: 'Page not found',
+		notFoundText: 'The requested page does not exist or may have moved.',
 		pageMoved: 'Page moved',
 		pageMovedText: 'This address now identifies',
 		pageNavigation: 'Page contents',
+		pageSequence: 'Page sequence',
+		pageSections: 'Sections',
 		previousImage: 'Previous image',
+		previousPage: 'Previous page',
+		returnHome: 'Go to the homepage',
+		search: 'Search',
+		searchDescription: 'Search the published content on this site.',
+		searchLoading: 'Loading search…',
+		searchNoScript: 'Search requires JavaScript. Use the page navigation when JavaScript is unavailable.',
+		searchUnavailable: 'Search is unavailable. During local work, run norna build:local to create or refresh the search index.',
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
@@ -224,8 +270,17 @@ const localeLabels = Object.freeze({
 		codeCopied: 'Kopierat',
 		codeCopyFailed: 'Kunde inte kopiera koden',
 		copyCode: 'Kopiera kod',
+		calloutCaution: 'Var försiktig',
+		calloutDanger: 'Fara',
+		calloutImportant: 'Viktigt',
+		calloutNote: 'Notera',
+		calloutTip: 'Tips',
+		calloutWarning: 'Varning',
+		editSource: 'Redigera den här sidan',
 		displaySettings: 'Visning',
 		focusReading: 'Fokuserad läsning',
+		footnoteBackReference: 'Tillbaka till referens {reference}',
+		footnotes: 'Fotnoter',
 		readingWidth: 'Textbredd',
 		readingWidthNarrow: 'Smal',
 		readingWidthStandard: 'Standard',
@@ -235,14 +290,36 @@ const localeLabels = Object.freeze({
 		built: 'Byggd',
 		images: 'Bilder',
 		imageCarousel: 'bildkarusell',
+		navigationCollapsedAll: 'Alla navigationsposter har fällts ihop.',
+		navigationCollapseAll: 'Fäll ihop alla',
+		navigationControls: 'Kontroller för navigationsträdet',
 		navigationChildren: 'Undersidor',
+		navigationExpandedAll: 'Alla navigationsposter har fällts ut.',
+		navigationExpandAll: 'Fäll ut alla',
+		navigationFilter: 'Filtrera sidor och grupper',
+		navigationFilterEmpty: 'Inga sidor eller grupper matchar. Den aktuella sidan är fortfarande tillgänglig.',
+		navigationFilterMatches: 'Matchande navigationsposter: {count}',
+		navigationLocatedCurrent: 'Den aktuella sidan har hittats.',
+		navigationLocateCurrent: 'Hitta aktuell sida',
 		navigationMenu: 'Meny',
 		nextImage: 'Nästa bild',
+		nextPage: 'Nästa sida',
 		note: 'Not',
+		notFound: 'Sidan hittades inte',
+		notFoundText: 'Den begärda sidan finns inte eller kan ha flyttats.',
 		pageMoved: 'Sidan har flyttats',
 		pageMovedText: 'Den här adressen identifierar nu',
 		pageNavigation: 'Sidinnehåll',
+		pageSequence: 'Sidföljd',
+		pageSections: 'Avsnitt',
 		previousImage: 'Föregående bild',
+		previousPage: 'Föregående sida',
+		returnHome: 'Gå till startsidan',
+		search: 'Sök',
+		searchDescription: 'Sök i det publicerade innehållet på webbplatsen.',
+		searchLoading: 'Laddar sökning…',
+		searchNoScript: 'Sökning kräver JavaScript. Använd sidnavigeringen när JavaScript inte är tillgängligt.',
+		searchUnavailable: 'Sökningen är inte tillgänglig. Kör norna build:local under lokalt arbete för att skapa eller uppdatera sökindexet.',
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
@@ -411,10 +488,13 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 			presentation: imagePresentation,
 			...(imagePresentation === 'centered-fit'
 				? {
-					maxAvailableHeightPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableHeightPercent', 'images', Object.freeze({
-						desktop: 74,
-						mobile: 68,
-					}), sourceLabel),
+					maxAvailableHeightPercent: readResponsivePercent(
+						rawImagesConfig,
+						'maxAvailableHeightPercent',
+						'images',
+						defaultImageMaxAvailableHeightPercent,
+						sourceLabel,
+					),
 				}
 				: {}),
 			maxAvailableWidthPercent: readResponsivePercent(rawImagesConfig, 'maxAvailableWidthPercent', 'images', Object.freeze({
@@ -457,12 +537,38 @@ export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) =
 	});
 };
 
+export const resolveEditLinkConfig = (config, sourceLabel = siteConfigLabel) => {
+	if (config.editLink === undefined) return null;
+
+	const rawEditLink = assertObject(config.editLink, 'editLink', sourceLabel);
+	if (!Object.hasOwn(rawEditLink, 'baseUrl')) {
+		throw new Error(`editLink.baseUrl is required when editLink is configured in ${sourceLabel}.`);
+	}
+	const unknownKeys = Object.keys(rawEditLink).filter((key) => key !== 'baseUrl');
+	if (unknownKeys.length > 0) {
+		throw new Error(`editLink.${unknownKeys[0]} is not a valid setting in ${sourceLabel}.`);
+	}
+
+	try {
+		return Object.freeze({
+			baseUrl: normalizeEditLinkBaseUrl(rawEditLink.baseUrl, 'editLink.baseUrl'),
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${message.replace(/\.$/, '')} in ${sourceLabel}.`);
+	}
+};
+
 export const projectConfig = Object.freeze({
 	site: Object.freeze({
 		basePath: siteUrl.pathname,
 		url: siteUrl.href,
 	}),
 	...resolveThemeVisualConfig(rawTheme, siteThemeLabel),
+	editLink: resolveEditLinkConfig(rawConfig, siteConfigLabel),
+	search: Object.freeze({
+		enabled: readBoolean(rawConfig, 'search', 'config YAML', false),
+	}),
 	navigation: Object.freeze({
 		...resolveNavigationConfig(rawConfig, siteConfigLabel),
 		scrollBehavior: readEnum(

package/scripts/lib/public-asset-conventions.mjs

@@ -18,10 +18,22 @@ export const browserIconAssetFilenames = Object.freeze(
 	browserIconAssetDefinitions.map(({ filename }) => filename),
 );
 
+export const socialImageAssetDefinitions = Object.freeze([
+	Object.freeze({ filename: 'social-image.png', type: 'image/png' }),
+	Object.freeze({ filename: 'social-image.jpg', type: 'image/jpeg' }),
+	Object.freeze({ filename: 'social-image.jpeg', type: 'image/jpeg' }),
+]);
+
+export const socialImageAssetFilenames = Object.freeze(
+	socialImageAssetDefinitions.map(({ filename }) => filename),
+);
+
 const logoExtensions = new Set(['.svg', '.png', '.jpg', '.jpeg']);
 const faviconExtensions = new Set(['.svg', '.png', '.ico']);
+const socialImageExtensions = new Set(['.png', '.jpg', '.jpeg']);
 const exactLogoNames = new Set(logoAssetFilenames);
 const exactBrowserIconNames = new Set(browserIconAssetFilenames);
+const exactSocialImageNames = new Set(socialImageAssetFilenames);
 
 export const isLogoAssetFilename = (filename) => exactLogoNames.has(filename);
 
@@ -60,6 +72,13 @@ const getSuspiciousAsset = (filename) => {
 		};
 	}
 
+	if (exactSocialImageNames.has(lowerFilename) && filename !== lowerFilename) {
+		return {
+			code: 'public-asset-case',
+			message: `Norna does not recognize "${filename}" as the social sharing image on case-sensitive file systems. Rename it to "${lowerFilename}".`,
+		};
+	}
+
 	if (parsed.name === 'logo' && !logoExtensions.has(parsed.ext)) {
 		return {
 			code: 'unsupported-logo-file',
@@ -74,6 +93,13 @@ const getSuspiciousAsset = (filename) => {
 		};
 	}
 
+	if (parsed.name === 'social-image' && !socialImageExtensions.has(parsed.ext)) {
+		return {
+			code: 'unsupported-social-image-file',
+			message: `Norna does not recognize "${filename}" as the social sharing image. Use exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+		};
+	}
+
 	if (/^favicon[-_.]/.test(lowerFilename) && !exactBrowserIconNames.has(lowerFilename)) {
 		return {
 			code: 'unrecognized-favicon-file',
@@ -95,6 +121,13 @@ const getSuspiciousAsset = (filename) => {
 		};
 	}
 
+	if (socialImageExtensions.has(parsed.ext) && editDistance(parsed.name, 'social-image') <= 2) {
+		return {
+			code: 'possible-social-image-typo',
+			message: `"${filename}" looks like a misspelled social sharing image filename. Norna recognizes ${socialImageAssetFilenames.join(', ')}.`,
+		};
+	}
+
 	return null;
 };
 
@@ -102,11 +135,12 @@ export const inspectPublicAssetFilenames = (filenames) => {
 	const files = [...filenames].sort((left, right) => left.localeCompare(right, 'en'));
 	const logos = files.filter(isLogoAssetFilename);
 	const browserIcons = files.filter((filename) => exactBrowserIconNames.has(filename));
+	const socialImages = files.filter((filename) => exactSocialImageNames.has(filename));
 	const suspicious = files.flatMap((filename) => {
-		if (isLogoAssetFilename(filename) || exactBrowserIconNames.has(filename)) return [];
+		if (isLogoAssetFilename(filename) || exactBrowserIconNames.has(filename) || exactSocialImageNames.has(filename)) return [];
 		const issue = getSuspiciousAsset(filename);
 		return issue ? [{ filename, ...issue }] : [];
 	});
 
-	return { browserIcons, files, logos, suspicious };
+	return { browserIcons, files, logos, socialImages, suspicious };
 };

package/scripts/lib/schema-definitions.mjs

@@ -17,13 +17,13 @@ const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width o
 const headingWeight = z.union([z.literal(400), z.literal(500), z.literal(600), z.literal(700)]).describe('CSS font weight.');
 const typographyProfile = z.enum(['restrained', 'dense', 'reading', 'statement']).describe('Coordinated typography defaults. Omit this to use the selected preset.');
 const themePreset = z.enum(themePresetNames).describe('Complete Norna visual preset. Start here and add overrides only when needed.');
-const presentationPalette = z.enum(presentationPaletteNames).describe('Coordinated site color palette. Every palette provides light and dark variants. Omit this to use the selected preset.');
+const presentationPalette = z.enum(presentationPaletteNames).describe('Coordinated site color palette. Every palette provides light and dark variants without changing the initial appearance. Omit this to use the selected preset.');
 const themeAppearance = z.object({
-	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial appearance. System follows the visitor\'s operating-system preference.'),
+	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial appearance. Omit this setting to follow the visitor\'s operating-system preference.'),
 }).strict().refine(
 	(value) => value.default !== undefined,
 	'Specify default.',
-).describe('Site-wide initial appearance.');
+).describe('Site-wide initial appearance. The default is system.');
 const readerControls = z.object({
 	appearance: z.boolean().optional().describe('Show an Appearance control that lets readers choose System, Light, or Dark.'),
 	focusReading: z.boolean().optional().describe('Show a Focus reading control that lets readers hide navigation, breadcrumbs, and the footer. Sites with tree navigation always show this control.'),
@@ -35,9 +35,24 @@ const spacingDensity = z.enum(['compact', 'normal', 'airy']).describe('Coordinat
 const contentSpacing = z.enum(['compact', 'normal', 'spacious']).describe('Vertical spacing between page sections and structured content blocks.');
 const backgroundPattern = z.enum(['uniform', 'alternating', 'accented']).describe('How coordinated backgrounds are assigned to H2 sections. Non-uniform patterns are unavailable with tree navigation.');
 const cornerTreatment = z.enum(['square', 'rounded']).describe('Site-wide corner treatment for navigation, cards and framed content.');
-const cardListWidth = z.enum(['text', 'narrow', 'normal', 'wide']).describe('Default maximum width for card lists. A width written in a norna-card-list block overrides this value.');
+const cardListWidth = z.enum(['text', 'narrow', 'normal', 'wide']).describe('Default maximum width for card lists. A width written in a card-list block overrides this value.');
 const imagePresentation = z.enum(imagePresentationNames).describe('How managed image stacks and carousels are placed on the page. Prose-aligned starts them at the body-text edge; centered-fit centers them and constrains them by available width and viewport height.');
-const navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation policy. Automatic selects an effective mode for each page from its active top-level branch.');
+const navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation policy. Automatic uses sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a hierarchical site.');
+const editLink = z.object({
+	baseUrl: z.string().url().refine((value) => {
+		try {
+			const url = new URL(value);
+			return ['http:', 'https:'].includes(url.protocol)
+				&& !url.username
+				&& !url.password
+				&& !url.search
+				&& !url.hash;
+		} catch {
+			return false;
+		}
+	}, 'Use an absolute http or https URL without credentials, a query string, or a fragment.')
+		.describe('Absolute edit URL prefix containing the repository, branch, and any repository subdirectory.'),
+}).strict().describe('Optional base URL for links from rendered pages to their Markdown source files.');
 const createLineHeight = (minimum, role) => z.number()
 	.min(minimum, `Use a unitless ${role} line height of at least ${minimum}.`)
 	.max(3, `Use a unitless ${role} line height of at most 3.`)
@@ -222,7 +237,9 @@ const sitewideFooter = z.object({
 const configShape = {
 	url: z.string().url().describe('Absolute public URL for the built site.'),
 	language: z.string().regex(/^(?:en|sv)(?:-[a-zA-Z0-9]+)*$/).optional().describe('Site language tag using Norna\'s English or Swedish interface text; the default is en.'),
+	editLink: editLink.optional(),
 	navigation: configNavigation.optional(),
+	search: z.boolean().optional().default(false).describe('Generate a static site search page and Pagefind index. The default is false.'),
 	scrollBehavior: z.enum(['instant', 'smooth']).optional().default('instant').describe('Use instant anchors by default or the browser\'s native smooth scrolling.'),
 };
 

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

@@ -159,11 +159,26 @@ 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, 'editLink', [
+		yamlExample('editLink:\n  baseUrl: https://github.com/owner/repository/edit/main/'),
+		'Adds a localized **Edit this page** link from each rendered page to its `content.md` source file. The base URL identifies the repository, branch, and any repository subdirectory; Norna appends the page source path.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	]);
+	addHelp(jsonSchema, 'editLink.baseUrl', [
+		yamlExample('editLink:\n  baseUrl: https://github.com/owner/repository/edit/main/'),
+		'Absolute edit URL prefix. Include any repository subdirectory and branch in this URL. Norna adds the project-relative path to each page\'s `content.md` file.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	], ['https://github.com/owner/repository/edit/main/']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  mode: automatic'),
-		'Sets the site-wide navigation policy. `automatic` selects an effective mode for each page from its active top-level branch.',
+		'Sets the site-wide navigation policy. `automatic` uses sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a hierarchical site.',
 		documentationLink('Navigation reference', 'pages.md', 'navigation'),
 	]);
+	addHelp(jsonSchema, 'search', [
+		yamlExample('search: true'),
+		'Generates a localized `/search/` page and a static Pagefind index during each build. Search is off by default, and only the search page loads the search JavaScript.',
+		documentationLink('Search reference', 'configuration.md', 'search'),
+	], [true, false]);
 	addFieldHelp(
 		jsonSchema,
 		'navigation.mode',
@@ -212,7 +227,7 @@ const addThemeHelp = (jsonSchema) => {
 	]);
 	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.',
+		'Sets site-wide defaults for card lists. A `width` option in an individual `card-list` block overrides this setting.',
 		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
 	]);
 	addFieldHelp(
@@ -241,12 +256,12 @@ const addThemeHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'palette', [
 		yamlExample('palette: warm-paper'),
-		'Chooses the site color character. Every palette provides coordinated light and dark variants.',
+		'Chooses the site color character. Every palette provides coordinated light and dark variants without changing the initial Appearance.',
 		documentationLink('Palette and appearance', 'theme.md', 'palette-and-appearance'),
 	], presentationPaletteNames);
 	addHelp(jsonSchema, 'appearance', [
 		yamlExample('appearance:\n  default: system'),
-		'Selects the initial appearance. Enable the reader-facing choice under readerControls.',
+		'Selects the initial Appearance. Omit this setting to follow the visitor\'s system preference. Enable the reader-facing choice under readerControls.',
 		documentationLink('Appearance', 'theme.md', 'appearance'),
 	]);
 	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);

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

@@ -23,7 +23,7 @@ export const schemaValueDefinitions = Object.freeze([
 		smooth: option('Browser smooth', 'Use the browser\'s native smooth scrolling for anchor navigation.'),
 	}),
 	definition(['automatic', 'sections', 'top', 'tree'], {
-		automatic: option('Automatic', 'Choose sections for one page, top navigation for Home and independent top-level pages, and tree navigation inside branches with listed children or categories.'),
+		automatic: option('Automatic', 'Choose sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a site with listed child pages or categories.'),
 		sections: option('Sections', 'Navigate the sections of the current page.'),
 		top: option('Top', 'Use pages in the top navigation and sections below them.'),
 		tree: option('Tree', 'Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.'),

package/scripts/lib/semantic-callouts.mjs

@@ -0,0 +1,128 @@
+export const semanticCalloutTypes = Object.freeze([
+	'NOTE',
+	'TIP',
+	'IMPORTANT',
+	'WARNING',
+	'CAUTION',
+	'DANGER',
+]);
+
+const semanticCalloutTypeSet = new Set(semanticCalloutTypes);
+const markerPattern = /^\[!([A-Za-z][A-Za-z0-9-]*)\]([^\n]*)(?:\n|$)/;
+
+const hasMeaningfulContent = (node) => {
+	if (!node || typeof node !== 'object') return false;
+	if ('value' in node && typeof node.value === 'string') return node.value.trim().length > 0;
+	if (node.type === 'image') return Boolean(node.alt);
+	return Array.isArray(node.children) && node.children.some(hasMeaningfulContent);
+};
+
+export const getSemanticCalloutMarker = (node) => {
+	if (node?.type !== 'blockquote') return null;
+	const firstParagraph = node.children?.[0];
+	const firstText = firstParagraph?.type === 'paragraph' ? firstParagraph.children?.[0] : null;
+	if (firstText?.type !== 'text') return null;
+
+	const match = firstText.value.match(markerPattern);
+	if (!match) {
+		return firstText.value.startsWith('[!')
+			? { malformed: true, firstParagraph, firstText }
+			: null;
+	}
+
+	const rawType = match[1] ?? '';
+	const type = rawType.toUpperCase();
+	const markerSource = match[0];
+	const title = (match[2] ?? '').trim();
+	const firstTextRemainder = firstText.value.slice(markerSource.length);
+	const firstParagraphRemainder = [
+		{ ...firstText, value: firstTextRemainder },
+		...(firstParagraph.children?.slice(1) ?? []),
+	];
+	const hasBody = firstParagraphRemainder.some(hasMeaningfulContent)
+		|| (node.children?.slice(1) ?? []).some(hasMeaningfulContent);
+
+	return {
+		firstParagraph,
+		firstText,
+		firstTextRemainder,
+		hasBody,
+		malformed: false,
+		markerSource,
+		rawType,
+		supported: semanticCalloutTypeSet.has(type),
+		title,
+		type,
+	};
+};
+
+const formatDiagnostic = ({ code, fix, label, line, message, offset }) => ({
+	code,
+	fix,
+	line,
+	message: `${label} line ${line}: ${message}`,
+	offset,
+});
+
+export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const label = options.label ?? 'Markdown';
+	const lineOffset = options.lineOffset ?? 0;
+
+	const visit = (node, blockquoteDepth = 0) => {
+		if (!node || typeof node !== 'object') return;
+		const nextBlockquoteDepth = blockquoteDepth + (node.type === 'blockquote' ? 1 : 0);
+		const marker = getSemanticCalloutMarker(node);
+
+		if (marker) {
+			const line = lineOffset + (node.position?.start.line ?? 1);
+			const offset = node.position?.start.offset ?? 0;
+			let issue = null;
+
+			if (blockquoteDepth > 0) {
+				issue = {
+					code: 'nested-semantic-callout',
+					message: 'Semantic callouts cannot be nested inside another blockquote or callout.',
+					fix: 'Move the inner callout after the surrounding blockquote.',
+				};
+			} else if (marker.malformed) {
+				issue = {
+					code: 'invalid-semantic-callout-marker',
+					message: 'This blockquote starts like a semantic callout but its marker is incomplete.',
+					fix: 'Write the marker on its own first line, for example "> [!WARNING]".',
+				};
+			} else if (marker.rawType !== marker.type) {
+				issue = {
+					code: 'invalid-semantic-callout-type-case',
+					message: `Semantic callout type "${marker.rawType}" must use uppercase ASCII letters.`,
+					fix: `Write "> [!${marker.type}]".`,
+				};
+			} else if (!marker.supported) {
+				issue = {
+					code: 'unknown-semantic-callout-type',
+					message: `Unknown semantic callout type "${marker.rawType}".`,
+					fix: `Use one of: ${semanticCalloutTypes.join(', ')}.`,
+				};
+			} else if (marker.title) {
+				issue = {
+					code: 'unsupported-semantic-callout-title',
+					message: `Semantic callout markers cannot contain a custom title ("${marker.title}").`,
+					fix: `Keep "> [!${marker.type}]" on its own line. Begin the callout body with bold text when local emphasis is useful.`,
+				};
+			} else if (!marker.hasBody) {
+				issue = {
+					code: 'empty-semantic-callout',
+					message: `${marker.type} callout has no content.`,
+					fix: 'Add at least one quoted content line after the marker.',
+				};
+			}
+
+			if (issue) diagnostics.push(formatDiagnostic({ ...issue, label, line, offset }));
+		}
+
+		for (const child of node.children ?? []) visit(child, nextBlockquoteDepth);
+	};
+
+	visit(tree);
+	return diagnostics;
+};

package/scripts/lib/site-content.mjs

@@ -30,6 +30,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'align',
 	'aliases',
 	'alt',
+	'baseUrl',
 	'body',
 	'blockGap',
 	'caption',
@@ -152,7 +153,7 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if (fileKind === 'content' && key === 'description') {
 			fix = 'Indent "description:" under "page:". The optional meta description belongs in the page object.';
 		} else if (fileKind === 'content' && key === 'images') {
-			fix = 'Put local image references in norna-image-stack or norna-image-carousel blocks in the Markdown body.';
+			fix = 'Put local image references in image-stack or 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 === 'theme' || fileKind === 'page theme') && key === 'navigation') {