@janga/norna 0.7.23 → 0.7.25

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 { localEditorNames, 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,18 @@ 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',
+		closeNavigation: 'Close navigation',
+		editSource: 'Edit this page',
 		displaySettings: 'Display',
 		focusReading: 'Focus reading',
+		footnoteBackReference: 'Back to reference {reference}',
+		footnotes: 'Footnotes',
 		readingWidth: 'Reading width',
 		readingWidthNarrow: 'Narrow',
 		readingWidthStandard: 'Standard',
@@ -203,17 +228,49 @@ const localeLabels = Object.freeze({
 		built: 'Built',
 		images: 'Images',
 		imageCarousel: 'image carousel',
+		imageInspection: 'Image inspection',
+		imageInspectionActualSize: 'Show actual size',
+		imageInspectionClose: 'Close image inspection',
+		imageInspectionFit: 'Fit image to window',
+		inspectImage: 'Inspect image: {description}',
+		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',
+		openInVsCode: 'Open in VS Code',
+		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',
+		tableColumns: 'Table columns',
+		tableNextColumns: 'Show next columns',
+		tableOverflowDescription: 'More table columns are available horizontally.',
+		tablePreviousColumns: 'Show previous columns',
 	}),
 	sv: Object.freeze({
 		breadcrumb: 'Brödsmulor',
@@ -224,8 +281,18 @@ 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',
+		closeNavigation: 'Stäng navigationen',
+		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,17 +302,49 @@ const localeLabels = Object.freeze({
 		built: 'Byggd',
 		images: 'Bilder',
 		imageCarousel: 'bildkarusell',
+		imageInspection: 'Bildgranskning',
+		imageInspectionActualSize: 'Visa faktisk storlek',
+		imageInspectionClose: 'Stäng bildgranskning',
+		imageInspectionFit: 'Anpassa bilden till fönstret',
+		inspectImage: 'Granska bild: {description}',
+		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',
+		openInVsCode: 'Öppna i VS Code',
+		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',
+		tableColumns: 'Tabellkolumner',
+		tableNextColumns: 'Visa nästa kolumner',
+		tableOverflowDescription: 'Fler tabellkolumner är tillgängliga i sidled.',
+		tablePreviousColumns: 'Visa föregående kolumner',
 	}),
 });
 
@@ -411,10 +510,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 +559,46 @@ 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);
+	const unknownKeys = Object.keys(rawEditLink).filter((key) => !['baseUrl', 'localEditor'].includes(key));
+	if (unknownKeys.length > 0) {
+		throw new Error(`editLink.${unknownKeys[0]} is not a valid setting in ${sourceLabel}.`);
+	}
+	if (!Object.hasOwn(rawEditLink, 'baseUrl') && !Object.hasOwn(rawEditLink, 'localEditor')) {
+		throw new Error(`editLink must specify baseUrl, localEditor, or both in ${sourceLabel}.`);
+	}
+
+	let baseUrl = null;
+	if (Object.hasOwn(rawEditLink, 'baseUrl')) {
+		try {
+			baseUrl = normalizeEditLinkBaseUrl(rawEditLink.baseUrl, 'editLink.baseUrl');
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`${message.replace(/\.$/, '')} in ${sourceLabel}.`);
+		}
+	}
+
+	return Object.freeze({
+		baseUrl,
+		localEditor: Object.hasOwn(rawEditLink, 'localEditor')
+			? readEnum(rawEditLink, 'localEditor', 'editLink', localEditorNames, undefined, sourceLabel)
+			: null,
+	});
+};
+
 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

@@ -1,4 +1,5 @@
 import { z } from 'astro/zod';
+import { localEditorNames } from './edit-source-link.mjs';
 import { imagePresentationNames } from './image-presentation.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
@@ -17,13 +18,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 +36,31 @@ 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.')
+		.optional(),
+	localEditor: z.enum(localEditorNames)
+		.optional()
+		.describe('Editor used by source links in a development preview opened through a loopback address.'),
+}).strict().refine(
+	(value) => value.baseUrl !== undefined || value.localEditor !== undefined,
+	'Specify baseUrl, localEditor, or both.',
+).describe('Optional local and remote 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 +245,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,43 @@ 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  localEditor: vscode\n  baseUrl: https://github.com/owner/repository/edit/main/'),
+		'Links each rendered page to its `content.md` source. A loopback development preview uses the explicitly selected local editor; published output and LAN previews use the optional remote base URL. Specify either destination or both.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	]);
+	const editLink = schemaProperty(jsonSchema, 'editLink');
+	editLink.anyOf = [{ required: ['localEditor'] }, { required: ['baseUrl'] }];
+	addSnippets(jsonSchema, 'editLink', [schemaSnippet({
+		label: 'Local and remote source links',
+		body: {
+			localEditor: 'vscode',
+			baseUrl: 'https://github.com/${1:owner}/${2:repository}/edit/${3:main}/',
+		},
+		description: 'Open page source in VS Code during same-computer development and on the remote source host elsewhere.',
+		file: 'configuration.md',
+		anchor: 'edit-link',
+	})]);
+	addHelp(jsonSchema, 'editLink.baseUrl', [
+		yamlExample('editLink:\n  baseUrl: https://github.com/owner/repository/edit/main/'),
+		'Optional absolute remote edit URL prefix. Include any repository subdirectory and branch. Norna adds the project-relative path to each page\'s `content.md` file. This destination is used by published output and LAN previews.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	], ['https://github.com/owner/repository/edit/main/']);
+	addHelp(jsonSchema, 'editLink.localEditor', [
+		yamlExample('editLink:\n  localEditor: vscode'),
+		'Optional editor for a development preview opened through localhost or another loopback address. `vscode` opens the absolute page source path through VS Code\'s registered URL handler. The setting is never emitted as a local path in published output.',
+		documentationLink('Edit-link reference', 'configuration.md', 'edit-link'),
+	], ['vscode']);
 	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 +244,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 +273,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.'),
@@ -32,6 +32,9 @@ export const schemaValueDefinitions = Object.freeze([
 		en: option('English', 'Use Norna\'s built-in English interface text.'),
 		sv: option('Swedish', 'Use Norna\'s built-in Swedish interface text.'),
 	}),
+	definition(['vscode'], {
+		vscode: option('Visual Studio Code', 'Open the current page source in the locally installed Visual Studio Code application.'),
+	}),
 	definition(['left', 'center', 'right'], {
 		left: option('Left', 'Align text with the left edge of its text area.'),
 		center: option('Center', 'Center text within its text area.'),