@janga/norna 0.7.22 → 0.7.24

package/scripts/lib/schema-definitions.mjs

@@ -1,4 +1,5 @@
 import { z } from 'astro/zod';
+import { imagePresentationNames } from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { themePresetNames } from './theme-presets.mjs';
@@ -16,26 +17,42 @@ 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 themeColorMode = z.object({
-	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial color mode. System follows the visitor\'s operating-system preference.'),
+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. Omit this setting to follow the visitor\'s operating-system preference.'),
 }).strict().refine(
 	(value) => value.default !== undefined,
 	'Specify default.',
-).describe('Site-wide light and dark mode behaviour.');
+).describe('Site-wide initial appearance. The default is system.');
 const readerControls = z.object({
-	colorMode: z.boolean().optional().describe('Let readers choose System, Light, or Dark color mode in the site-wide Display panel.'),
-	focusReading: z.boolean().optional().describe('Let readers temporarily hide navigation and other secondary page chrome while reading. Tree navigation always provides this control.'),
+	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.'),
 }).strict().refine(
-	(value) => value.colorMode !== undefined || value.focusReading !== undefined,
-	'Specify colorMode, focusReading, or both.',
-).describe('Optional site-wide reader choices grouped with the always-available reading-width choice in the Display panel.');
+	(value) => value.appearance !== undefined || value.focusReading !== undefined,
+	'Specify appearance, focusReading, or both.',
+).describe('Optional controls for the site-wide Display panel.');
 const spacingDensity = z.enum(['compact', 'normal', 'airy']).describe('Coordinated spacing density. Omit this to use the selected preset.');
 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 navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation model. Automatic selects from the site structure.');
+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 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.`)
@@ -156,10 +173,11 @@ const pageThemeLayout = z.object({
 	'Specify contentSpacing, textWidth, or both.',
 ).describe('Page-local layout settings inherited by descendant pages.');
 const themeImages = z.object({
+	presentation: imagePresentation.optional().describe('Managed-image presentation method. Omit this to keep the selected preset or inherited page setting.'),
 	width: visualCssLength.optional().describe('Maximum managed-image width. Omit this to keep the selected preset.'),
 	maxAvailableWidthPercent: responsivePercent.optional().describe('Maximum percentage of available horizontal space used by managed images.'),
-	maxAvailableHeightPercent: responsivePercent.optional().describe('Maximum percentage of viewport height used by managed images.'),
-}).strict().describe('Optional defaults for managed image presentation.');
+	maxAvailableHeightPercent: responsivePercent.optional().describe('Maximum percentage of viewport height used by centered-fit images. This setting is unavailable with prose-aligned presentation.'),
+}).strict().describe('Optional defaults for placing managed images inside the page content area. Persistent navigation remains outside this area.');
 const themeCardList = z.object({
 	width: cardListWidth,
 }).strict().describe('Site-wide card-list defaults.');
@@ -171,7 +189,6 @@ const themeBlocks = z.object({
 ).describe('Optional site-wide defaults for structured Norna content blocks.');
 const configNavigation = z.object({
 	mode: navigationMode.optional().describe('Navigation model. Omit this to let Norna choose from the site structure.'),
-	sectionTracking: z.boolean().optional().default(false).describe('As the reader scrolls in tree navigation, mark the last H2 or H3 that has reached the reading area below the sticky header. The URL and keyboard focus do not change.'),
 }).strict().describe('Site-wide navigation behavior.');
 const themeSections = z.object({
 	backgroundPattern: backgroundPattern.optional().describe('Section background pattern. Alternating and accented create full-width bands with sections or top navigation; tree navigation requires uniform.'),
@@ -185,8 +202,17 @@ const pageThemeSections = z.object({
 const pageNavigation = z.object({
 	listed: z.boolean().optional().default(true).describe('List this page in site navigation. The page remains public when false.'),
 }).strict();
+const pageAlias = z.string().regex(
+	/^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+$/,
+	'Use an old site-relative Norna page URL such as "/guides/install/". Start and end with / and use lowercase letters, numbers, and single hyphens.',
+).describe('Previous site-relative URL that permanently identifies this page.');
 const pageMetadata = z.object({
 	description: z.string().min(1).optional().describe('Optional page-specific meta description.'),
+	aliases: z.array(pageAlias)
+		.min(1)
+		.refine((values) => new Set(values).size === values.length, 'Page aliases must be unique within the page.')
+		.optional()
+		.describe('Previous site-relative URLs that permanently identify this page. The current page is always the target.'),
 }).strict().describe('Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title.');
 const sitewideLogo = z.object({
 	height: visualCssLength.optional().describe('Displayed logo height on wider screens. Omit it to use 2.6rem; narrow screens cap the height at 2.15rem. Width follows the intrinsic aspect ratio.'),
@@ -211,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.'),
 };
 
@@ -222,7 +250,7 @@ const siteShape = {
 
 const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
-	colorMode: themeColorMode.optional(),
+	appearance: themeAppearance.optional(),
 	readerControls: readerControls.optional(),
 	corners: cornerTreatment.optional().describe('Site-wide corner treatment. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),

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

@@ -33,6 +33,13 @@ const schemaProperty = (schema, propertyPath) => schemaProperties(schema, proper
 const addHelp = (schema, propertyPath, paragraphs, examples = []) => {
 	for (const property of schemaProperties(schema, propertyPath)) {
 		property.markdownDescription = paragraphs.join('\n\n');
+		const reference = paragraphs.findLast((paragraph) => /^\[[^\]]+\]\(https:\/\//.test(paragraph));
+		if (reference && Array.isArray(property.oneOf)) {
+			for (const candidate of property.oneOf) {
+				if (!Object.hasOwn(candidate, 'const') || !candidate.description) continue;
+				candidate.markdownDescription = [candidate.description, reference].join('\n\n');
+			}
+		}
 		if (examples.length > 0) property.examples = examples;
 	}
 };
@@ -152,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 one navigation model for the complete site. `automatic` selects from the page hierarchy.',
+		'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',
@@ -165,14 +187,6 @@ const addConfigHelp = (jsonSchema) => {
 		'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.',
@@ -202,8 +216,8 @@ const addThemeHelp = (jsonSchema) => {
 		documentationLink('Layout reference', 'theme.md', 'layout'),
 	]);
 	addHelp(jsonSchema, 'images', [
-		yamlExample('images:\n  width: 900px\n  maxAvailableHeightPercent: 74'),
-		'Overrides the available width and height used by Norna-managed images.',
+		yamlExample('images:\n  presentation: prose-aligned\n  width: 900px'),
+		'Overrides how Norna-managed image stacks and carousels align inside the page content area and how much space they may use. Persistent navigation remains outside this area.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
 	addHelp(jsonSchema, 'blocks', [
@@ -213,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(
@@ -242,29 +256,31 @@ const addThemeHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'palette', [
 		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'),
+		'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, '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'),
+	addHelp(jsonSchema, 'appearance', [
+		yamlExample('appearance:\n  default: system'),
+		'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, '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}',
+	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
+	addSnippets(jsonSchema, 'appearance', [schemaSnippet({
+		label: 'Set the initial appearance',
+		body: 'appearance:\n  default: ${1:system}',
 		description: 'Follow the system color preference or choose a fixed initial appearance.',
 		file: 'theme.md',
-		anchor: 'color-mode',
+		anchor: 'appearance',
 	})]);
 	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.',
+		yamlExample('readerControls:\n  appearance: true\n  focusReading: true'),
+		'Choose which optional controls readers can use in the site-wide Display panel.',
+		'`appearance: true` lets readers choose System, Light, or Dark. `focusReading: true` lets them hide navigation, breadcrumbs, and the footer while reading.',
+		'Reading width is always included. Sites with tree navigation always include Focus reading, even when it is not enabled here.',
 		documentationLink('Reader Display controls', 'theme.md', 'reader-display-controls'),
 	]);
 	for (const [propertyPath, example] of [
-		['readerControls.colorMode', 'readerControls:\n  colorMode: true'],
+		['readerControls.appearance', 'readerControls:\n  appearance: true'],
 		['readerControls.focusReading', 'readerControls:\n  focusReading: true'],
 	]) {
 		addFieldHelp(
@@ -277,8 +293,8 @@ const addThemeHelp = (jsonSchema) => {
 	}
 	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.',
+		body: 'readerControls:\n  appearance: ${1:true}\n  focusReading: ${2:true}',
+		description: 'Show optional Appearance and Focus reading controls. Reading width is already included, and tree navigation always includes Focus reading.',
 		file: 'theme.md',
 		anchor: 'reader-display-controls',
 	})]);
@@ -352,6 +368,7 @@ const addThemeHelp = (jsonSchema) => {
 	})]);
 
 	const imageFields = [
+		['images.presentation', 'images:\n  presentation: prose-aligned'],
 		['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'],
@@ -464,11 +481,12 @@ const addPageThemeHelp = (jsonSchema) => {
 	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.',
+		yamlExample('images:\n  presentation: prose-aligned\n  width: 900px'),
+		'Adjusts managed-image presentation and sizing inside the content area for pages below this directory. Persistent navigation remains outside this area.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
 	const imageFields = [
+		['images.presentation', 'images:\n  presentation: prose-aligned'],
 		['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'],
@@ -563,8 +581,8 @@ const addContentHelp = (jsonSchema) => {
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'page', [
-		yamlExample('page:\n  description: About this project.'),
-		'Contains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title.',
+		yamlExample('page:\n  description: About this project.\n  aliases:\n    - /old-about/'),
+		'Contains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title. An alias records an old URL for this same page.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	]);
 	addHelp(jsonSchema, 'page.description', [
@@ -572,6 +590,16 @@ const addContentHelp = (jsonSchema) => {
 		'An optional page-specific description rendered as `<meta name="description">`. It is not visible in page content.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	], ['About this project.']);
+	addHelp(jsonSchema, 'page.aliases', [
+		yamlExample('page:\n  aliases:\n    - /old-about/'),
+		'Lists previous site-relative URLs that permanently identify this page. The page containing the list is always the target. Paths omit the configured base path and are excluded from the sitemap.',
+		documentationLink('Preserve old page URLs', 'pages.md', 'preserve-old-page-urls'),
+	], [['/old-about/']]);
+	addHelp(jsonSchema, 'page.aliases.[]', [
+		yamlExample('page:\n  aliases:\n    - /old-about/'),
+		'Use a previous Norna page URL. Start and end with `/`; use lowercase ASCII letters, numbers, and single hyphens; do not include the configured base path, a query string, or a fragment.',
+		documentationLink('Alias path rules', 'pages.md', 'preserve-old-page-urls'),
+	], ['/old-about/']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  listed: false'),
 		'Optionally excludes an additional page from site navigation without removing its public URL.',

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

@@ -23,10 +23,10 @@ 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 a shallow multi-page site, and tree navigation for deeper content.'),
+		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 hierarchical site-wide navigation tree.'),
+		tree: option('Tree', 'Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.'),
 	}),
 	definition(['en', 'sv'], {
 		en: option('English', 'Use Norna\'s built-in English interface text.'),
@@ -54,6 +54,10 @@ export const schemaValueDefinitions = Object.freeze([
 		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(['prose-aligned', 'centered-fit'], {
+		'prose-aligned': option('Prose-aligned', 'Start managed images and captions at the body-text edge and size them from the page content area.'),
+		'centered-fit': option('Centered fit', 'Center managed images and captions in the page media area and constrain them by available width and viewport height.'),
+	}),
 	definition([400, 500, 600, 700], {
 		400: option('Regular', 'Use regular font weight.'),
 		500: option('Medium', 'Use medium font weight.'),

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

@@ -1,11 +1,15 @@
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import {
+	schemaTopLevelKeys,
+	siteSchema,
+} from './schema-definitions.mjs';
 import {
 	siteContentLabel,
 	sitewideContentLabel,
 } from './site-paths.mjs';
-import { schemaTopLevelKeys } from './schema-definitions.mjs';
 import { getIndentInfo, validateYamlIndentation } from './yaml-indentation.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
 
 export { getContentFiles } from './site-structure.mjs';
 
@@ -24,11 +28,13 @@ const knownPageThemeTopLevelFrontmatterKeys = new Set(
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
+	'aliases',
 	'alt',
+	'baseUrl',
 	'body',
 	'blockGap',
 	'caption',
-	'colorMode',
+	'appearance',
 	'carousel',
 	'contentSpacing',
 	'desktop',
@@ -104,7 +110,10 @@ export const splitSiteFile = (source, label = siteContentLabel) => {
 	};
 };
 
-export const readSiteFile = async (sitePath, label = siteContentLabel) => splitSiteFile(await readFile(sitePath, 'utf8'), label);
+export const readSiteFile = async (sitePath, label = siteContentLabel) => {
+	const source = await readFile(sitePath, 'utf8');
+	return { ...splitSiteFile(source, label), source };
+};
 
 export const validateFrontmatterIndentation = (frontmatter, addIssue) => {
 	validateYamlIndentation(frontmatter, (issue) => addIssue({
@@ -144,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') {
@@ -157,7 +166,12 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 			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)) {
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'colorMode') {
+			message = `Frontmatter line ${lineNumber}: Theme setting "colorMode" was replaced by "appearance".`;
+			fix = fileKind === 'page theme'
+				? 'Remove "colorMode:" from this page theme. Set "appearance:" in the root theme.yaml when an override is needed.'
+				: 'Replace "colorMode:" with "appearance:".';
+		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'readerControls', '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)) {
@@ -186,6 +200,15 @@ export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
 		fileKind: 'content',
 	});
 
+export const parseContentFrontmatter = (frontmatterBody, label = siteContentLabel) => parseYamlConfig(
+	frontmatterBody,
+	`${label} frontmatter`,
+	{
+		schema: siteSchema,
+		validateStructure: validateContentFrontmatterStructure,
+	},
+);
+
 export const validateConfigYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownConfigTopLevelFrontmatterKeys,