@janga/norna 0.7.22 → 0.7.23

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';
@@ -17,25 +18,26 @@ const headingWeight = z.union([z.literal(400), z.literal(500), z.literal(600), z
 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 themeAppearance = z.object({
+	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial appearance. System follows 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.');
 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 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 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 +158,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 +174,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 +187,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.'),
@@ -222,7 +233,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;
 	}
 };
@@ -154,7 +161,7 @@ const addConfigHelp = (jsonSchema) => {
 	], ['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.',
+		'Sets the site-wide navigation policy. `automatic` selects an effective mode for each page from its active top-level branch.',
 		documentationLink('Navigation reference', 'pages.md', 'navigation'),
 	]);
 	addFieldHelp(
@@ -165,14 +172,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 +201,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', [
@@ -243,28 +242,30 @@ 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'),
+		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. 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 +278,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 +353,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 +466,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 +566,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 +575,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 Home and independent top-level pages, and tree navigation inside branches with listed children 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/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,12 @@ const knownPageThemeTopLevelFrontmatterKeys = new Set(
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
+	'aliases',
 	'alt',
 	'body',
 	'blockGap',
 	'caption',
-	'colorMode',
+	'appearance',
 	'carousel',
 	'contentSpacing',
 	'desktop',
@@ -104,7 +109,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({
@@ -157,7 +165,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 +199,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,