@janga/norna 0.7.27 → 0.7.29

package/scripts/lib/page-order.mjs

@@ -0,0 +1,45 @@
+// One ordering contract for source discovery, placement and presentation.
+export const pageOrderSpacing = 1000;
+export const maximumPageOrder = Number.MAX_SAFE_INTEGER;
+
+export const parsePageOrder = (value, label = 'navigation.order') => {
+	if (value === undefined || value === null) return null;
+	if (!Number.isSafeInteger(value) || value < 1) {
+		throw new Error(`${label} must be a positive safe integer (1–${maximumPageOrder}).`);
+	}
+	return value;
+};
+
+export const comparePageOrder = (left, right) => {
+	const a = left.pageOrder ?? null, b = right.pageOrder ?? null;
+	return (a === null ? b === null ? 0 : 1 : b === null ? -1 : a - b)
+		|| (left.pageId < right.pageId ? -1 : left.pageId > right.pageId ? 1 : 0);
+};
+
+// Siblings exclude the inserted page and are already in presentation order.
+export const planPageOrder = (siblings, index) => {
+	if (!Number.isInteger(index) || index < 0 || index > siblings.length) throw new Error('Invalid page insertion position.');
+	const before = index === 0 ? 0 : siblings[index - 1].pageOrder;
+	const after = siblings[index]?.pageOrder ?? null;
+	let order = null;
+	if (before !== null && before !== undefined) {
+		if (after !== null && after - before > 1) order = before + Math.floor((after - before) / 2);
+		else if (after === null && before <= maximumPageOrder - pageOrderSpacing) order = before + pageOrderSpacing;
+	}
+	if (order !== null) return { order, orderChanges: [] };
+	if (siblings.length + 1 > Math.floor(maximumPageOrder / pageOrderSpacing)) throw new Error('Too many siblings to assign safe page order values.');
+	const orderChanges = siblings.flatMap((node, position) => {
+		const newOrder = (position + (position >= index ? 2 : 1)) * pageOrderSpacing;
+		return node.pageOrder === newOrder ? [] : [{ node, oldOrder: node.pageOrder, newOrder }];
+	});
+	return { order: (index + 1) * pageOrderSpacing, orderChanges };
+};
+
+export const describeRenumbering = (changes, displayPath = value => value) => changes.length ? [
+	`This placement requires new order values for ${changes.length} existing sibling page(s). Their content.md files will be updated:`,
+	...changes.map(change => `- ${displayPath(change.contentPath ?? change.node.contentPath)}: ${change.oldOrder ?? 'unset'} → ${change.newOrder}`),
+].join('\n') : '';
+
+export const assertRenumberingAllowed = (changes, allowRenumber) => {
+	if (changes.length && allowRenumber !== true) throw new Error('Renumbering existing sibling pages requires confirmation. Review the plan; use --allow-renumber for unattended commands. No files changed.');
+};

package/scripts/lib/page-placement-cli.mjs

@@ -0,0 +1,50 @@
+import { createInterface } from 'node:readline/promises';
+import { parsePageOrder, assertRenumberingAllowed, describeRenumbering } from './page-order.mjs';
+
+export const parsePlacementArguments = (args) => {
+ const options = { positionals: [], order: null, parent: null, slug: null, placement: null, target: null, preserveAliases: true };
+ const seen = new Set();
+ const flags = { '--help': 'help', '-h': 'help', '--dry-run': 'dryRun', '--write': 'write', '--allow-renumber': 'allowRenumber', '--no-aliases': 'noAliases', '--first': 'first', '--last': 'last' };
+ const values = { '--parent': 'parent', '--slug': 'slug', '--order': 'order', '--before': 'before', '--after': 'after' };
+ for (let i = 0; i < args.length; i++) {
+  const [name, ...tail] = args[i].split('=');
+  const key = flags[name] ?? values[name];
+  if (!key) {
+   if (args[i].startsWith('-')) throw new Error(`Unknown option: ${args[i]}`);
+   options.positionals.push(args[i]); continue;
+  }
+  if (seen.has(key)) throw new Error(`${name} may be specified only once.`);
+  seen.add(key);
+  if (flags[name]) {
+   if (tail.length) throw new Error(`${name} does not take a value.`);
+   options[key] = true;
+  } else {
+   const value = tail.length ? tail.join('=') : args[++i];
+   if (!value || value.startsWith('--')) throw new Error(`${name} requires a value.`);
+   options[key] = value;
+  }
+ }
+ if (options.order !== null) {
+  if (!/^\d+$/.test(options.order)) throw new Error('--order must be a positive integer.');
+  options.order = parsePageOrder(Number(options.order), '--order');
+ }
+ const positions = ['before', 'after', 'first', 'last'].filter(key => seen.has(key));
+ if (positions.length > 1) throw new Error('Choose only one of --before, --after, --first or --last.');
+ options.placement = positions[0] ?? (options.parent !== null ? 'last' : null);
+ if ((options.before || options.after) && options.parent !== null) throw new Error('--before/--after determine the parent; do not combine them with --parent.');
+ if (positions.length && options.order !== null) throw new Error('Do not combine --order with a placement selector.');
+ if (options.dryRun && options.write) throw new Error('Choose --dry-run or --write, not both.');
+ options.target = options.before ?? options.after ?? options.parent ?? '/';
+ options.preserveAliases = !options.noAliases;
+ return options;
+};
+
+export const confirmCliRenumbering = async (changes, options) => {
+ if (!changes.length) return true;
+ if (options.allowRenumber) return true;
+ if (!process.stdin.isTTY || !process.stdout.isTTY) assertRenumberingAllowed(changes, false);
+ const prompt = createInterface({ input: process.stdin, output: process.stdout });
+ try { return /^(y|yes)$/i.test((await prompt.question('Apply these order changes? [y/N] ')).trim()); }
+ finally { prompt.close(); }
+};
+export { describeRenumbering };

package/scripts/lib/presentation.mjs

@@ -453,7 +453,7 @@ export const getPresentationCssVariables = (presentation) => {
 	return variables;
 };
 
-const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') => {
+const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'root/tree-theme.yaml') => {
 	const surfaces = sectionBackgroundPatterns[pattern];
 	if (!surfaces) {
 		throw new Error(`sections.backgroundPattern must be one of ${Object.keys(sectionBackgroundPatterns).join(', ')} in ${sourceLabel}.`);
@@ -462,7 +462,7 @@ const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') =>
 	return surfaces;
 };
 
-export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
+export const resolveThemePresentation = (theme, sourceLabel = 'root/tree-theme.yaml') => {
 	const normalizedTheme = resolveThemeConfig(theme, sourceLabel);
 	const paletteName = normalizedTheme.palette ?? 'near-monochrome';
 	const palette = getPresentationPalette(paletteName);
@@ -509,7 +509,7 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 
 export const assertSectionBackgroundPatternCompatibility = (
 	theme,
-	sourceLabel = 'theme.yaml',
+	sourceLabel = 'root/tree-theme.yaml',
 	navigationMode = 'sections',
 ) => {
 	const requestedPattern = theme?.sections?.backgroundPattern;

package/scripts/lib/project-config.mjs

@@ -1,4 +1,7 @@
+import { assertSiteSourceFormat } from './site-source-format.mjs';
 import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import {
 	validateConfigYamlStructure,
 } from './site-content.mjs';
@@ -11,6 +14,7 @@ import { navigationModeNames } from './navigation-model.mjs';
 import {
 	siteConfigLabel,
 	siteConfigPath,
+	siteDir,
 	siteThemeLabel,
 } from './site-paths.mjs';
 import { localEditorNames, normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
@@ -20,6 +24,9 @@ import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
 
 const readSiteConfig = async () => {
+	if (existsSync(path.join(siteDir, 'site-config/site-theme.yaml')) || existsSync(path.join(siteDir, 'root/theme.yaml')) || existsSync(path.join(siteDir, 'config.yaml')) || existsSync(path.join(siteDir, 'page-theme.yaml')) || existsSync(path.join(siteDir, 'sitewide-content.yaml'))) {
+		throw new Error('This site has configuration files in the former locations. Stop its development server and follow the source-layout reference to place technical settings in site-config/ and page files in root/. Move the shared theme to root/tree-theme.yaml with an explicit preset and homepage-only overrides to root/page-theme.yaml. Automatic historical conversion is not provided.');
+	}
 	const source = await readFile(siteConfigPath, 'utf8').catch((error) => {
 		if (error?.code === 'ENOENT') {
 			throw new Error(`${siteConfigLabel} is required. Create it before running Norna.`);
@@ -28,6 +35,7 @@ const readSiteConfig = async () => {
 		throw error;
 	});
 
+	await assertSiteSourceFormat(siteDir);
 	return parseYamlConfig(source, siteConfigLabel, {
 		validateStructure: validateConfigYamlStructure,
 	});
@@ -302,13 +310,6 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 		defaultImagePresentation,
 		sourceLabel,
 	);
-	if (imagePresentation === 'prose-aligned' && rawImagesConfig.maxAvailableHeightPercent !== undefined) {
-		throw new Error([
-			`images.maxAvailableHeightPercent cannot be used with images.presentation "prose-aligned" in ${sourceLabel}.`,
-			'Prose-aligned images follow available horizontal space instead of a viewport-height limit.',
-			'Remove images.maxAvailableHeightPercent or set images.presentation to "centered-fit".',
-		].join('\n'));
-	}
 
 	return Object.freeze({
 		layout: Object.freeze({
@@ -371,7 +372,7 @@ export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) =
 	if (Object.hasOwn(rawNavigation, 'sectionTracking')) {
 		throw new Error([
 			`navigation.sectionTracking is no longer supported in ${sourceLabel}.`,
-			'Section tracking is automatic on pages with a contents rail.',
+			'Section tracking is automatic on tree-navigation pages with H2 headings.',
 			'Remove navigation.sectionTracking.',
 		].join('\n'));
 	}
@@ -424,6 +425,7 @@ export const projectConfig = Object.freeze({
 		url: siteUrl.href,
 	}),
 	...resolveThemeVisualConfig(rawTheme, siteThemeLabel),
+	verificationFiles: Object.freeze(rawConfig.verificationFiles ?? []),
 	editLink: resolveEditLinkConfig(rawConfig, siteConfigLabel),
 	search: Object.freeze({
 		enabled: readBoolean(rawConfig, 'search', 'config YAML', false),

package/scripts/lib/publication-paths.mjs

@@ -0,0 +1,72 @@
+import { logoAssetFilenames, browserIconAssetFilenames, socialImageAssetFilenames } from './public-asset-conventions.mjs';
+
+export const resourcePrefix = '/_norna/';
+export const attachmentOutputPrefix = `${resourcePrefix}downloads/`;
+export const sharedOutputPrefix = `${resourcePrefix}shared/`;
+export const searchOutputDirectory = '_norna/search';
+export const compiledOutputDirectory = '_norna/assets';
+const technicalFiles = new Set(['robots.txt', 'CNAME', 'llms.txt']);
+const siteImages = new Set([...logoAssetFilenames, ...browserIconAssetFilenames, ...socialImageAssetFilenames]);
+const key = value => value.normalize('NFC').toLowerCase();
+const reservedRoots = new Set(['_norna', '_astro', 'images', 'sitemap.xml', '404.html', '.well-known']);
+const safeSegment = value => Boolean(value) && value === value.trim() && !/[\\/\x00-\x1f\x7f<>:"|?*#%]/.test(value) && !/^\.{1,2}$/.test(value) && !/[. ]$/.test(value);
+
+export const isVerificationFilename = value => typeof value === 'string' && safeSegment(value)
+	&& !value.startsWith('.') && !reservedRoots.has(key(value))
+	&& ![...technicalFiles, ...siteImages].some(name => key(name) === key(value));
+
+export const attachmentPublicationPath = (pagePathname, filename) => {
+	// Double hyphens and ~ cannot occur inside a page slug. Keep the complete
+	// page identity in one segment so extensionless files cannot shadow children.
+	const pageKey = pagePathname === '/' ? '~home' : pagePathname.slice(1, -1).split('/').join('--');
+	return `${attachmentOutputPrefix}${pageKey}/${filename}`;
+};
+
+export const publicFilePublication = (relativePath, { verificationFiles = [] } = {}, { directory = false } = {}) => {
+	const segments = relativePath.split('/');
+	if (!segments.every(safeSegment)) throw new Error(`public/${relativePath} has an unsafe path. Use regular names without URL punctuation or parent-directory segments.`);
+	if (directory) {
+		if (segments[0] === '.well-known') return { pathname: '/' + relativePath, kind: 'public-directory' };
+		throw new Error(`public/${relativePath}/ is not a supported public folder. Put content images in the owning page’s images/ beside content.md. Only .well-known/ is supported here, for technical files.`);
+	}
+	if (technicalFiles.has(relativePath) || segments[0] === '.well-known' && segments.length > 1 || verificationFiles.includes(relativePath) && isVerificationFilename(relativePath)) {
+		return { pathname: '/' + relativePath, kind: 'technical-file' };
+	}
+	if (siteImages.has(relativePath)) {
+		return { pathname: sharedOutputPrefix + relativePath, kind: 'shared-image' };
+	}
+	const generated = ['_norna', '_astro', 'sitemap.xml', '404.html'].includes(key(segments[0]));
+	throw new Error(`public/${relativePath} ${generated ? 'conflicts with a generated resource area' : 'is not a supported public file'}. Put content images in the owning page’s images/ beside content.md and documents in its downloads/. Public images must use a recognized logo, favicon, apple-touch-icon or social-image filename. Declare exact root verification filenames in verificationFiles.`);
+};
+
+export const publicationIssues = ({ pages = [], publicFiles = [], attachments = [], images = [], generatedRoutes = [] } = {}) => {
+	const issues = [];
+	const outputs = [];
+	const add = (pathname, label, owner) => outputs.push({ pathname, label, owner });
+	for (const page of pages) {
+		const label = page.contentFile?.contentLabel ?? page.contentLabel ?? page.pathname;
+		for (const route of [page.pathname, ...(page.aliases ?? [])]) {
+			if (!route) continue;
+			if (['/_norna', '/_astro', '/.well-known'].some(prefix => key(route) === prefix || key(route).startsWith(prefix + '/'))) {
+				issues.push({ severity: 'error', code: 'reserved-publication-path', message: `${label} claims ${route}, which belongs to Norna or technical public files.`, fix: 'Choose a page or alias outside the reserved area.' });
+			}
+			add(route + 'index.html', route === page.pathname ? label : `${label} (alias ${route})`, 'page');
+		}
+	}
+	for (const file of publicFiles) add(file.pathname, file.label ?? file.filePath ?? file.pathname, 'public');
+	for (const file of attachments) add(file.pathname, file.filePath ?? file.pathname, 'attachment');
+	for (const file of images) add(file.pathname, file.label, 'image');
+	for (const route of generatedRoutes) add(route.pathname.endsWith('/') ? route.pathname + 'index.html' : route.pathname, route.label ?? route.pathname, 'generated');
+	// 404 is always generated, including sites without a search page.
+	if (!generatedRoutes.some(route => route.pathname === '/404.html')) add('/404.html', 'Norna generated 404 page', 'generated');
+	const seen = [];
+	for (const output of outputs) {
+		const target = key(output.pathname);
+		const conflict = seen.find(candidate => target === candidate.key || target.startsWith(candidate.key + '/') || candidate.key.startsWith(target + '/'));
+		if (conflict) issues.push({ severity: 'error', code: output.owner === 'attachment' || conflict.owner === 'attachment' ? 'attachment-output-collision' : 'publication-collision',
+			message: `${output.label} publishes ${output.pathname}, which conflicts with ${conflict.label} at ${conflict.pathname}.`,
+			fix: 'Rename or relocate the conflicting source. Each published path must have one owner.' });
+		seen.push({ ...output, key: target });
+	}
+	return issues;
+};

package/scripts/lib/schema-definitions.mjs

@@ -1,3 +1,4 @@
+import { isVerificationFilename } from './publication-paths.mjs';
 import { z } from 'astro/zod';
 import { localEditorNames } from './edit-source-link.mjs';
 import { imagePresentationNames } from './image-presentation.mjs';
@@ -167,13 +168,6 @@ const themeLayout = z.object({
 	gutter: responsiveCssLength.optional().describe('Horizontal page gutter as one value or separate desktop and mobile values.'),
 	spacing: themeLayoutSpacing.optional().describe('Fine-grained spacing overrides.'),
 }).strict().describe('Optional layout overrides applied after the preset.');
-const pageThemeLayout = z.object({
-	contentSpacing: contentSpacing.optional().describe('Page content spacing. Descendant pages inherit this value.'),
-	textWidth: textWidth.optional().describe('Body-text line length. Descendant pages inherit this value.'),
-}).strict().refine(
-	(value) => value.contentSpacing !== undefined || value.textWidth !== undefined,
-	'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.'),
@@ -182,26 +176,21 @@ const themeImages = z.object({
 }).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.');
+}).strict().describe('Card-list defaults.');
 const themeBlocks = z.object({
 	cardList: themeCardList.optional(),
 }).strict().refine(
 	(value) => value.cardList !== undefined,
 	'Specify cardList.',
-).describe('Optional site-wide defaults for structured Norna content blocks.');
+).describe('Optional defaults for structured Norna content blocks.');
 const configNavigation = z.object({
 	mode: navigationMode.optional().describe('How Norna presents the discovered page and heading hierarchy. Omit this to select automatic.'),
 }).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.'),
 }).strict().describe('Defaults for page section presentation.');
-const pageThemeSections = z.object({
-	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.'),
-}).strict().refine(
-	(value) => value.backgroundPattern !== undefined,
-	'Specify backgroundPattern.',
-).describe('Page-local section presentation inherited by descendant pages.');
 const pageNavigation = z.object({
+	order: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional().describe('Sibling presentation order. Positive integer; lower values appear first. Omit to follow ordered siblings, sorted by slug. Duplicate values warn and use slug to break ties.'),
 	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(
@@ -210,6 +199,7 @@ const pageAlias = z.string().regex(
 ).describe('Previous site-relative URL that permanently identifies this page.');
 const pageMetadata = z.object({
 	description: z.string().min(1).optional().describe('Page description used in metadata, social previews and generated child-page lists.'),
+	listChildren: z.boolean().optional().describe('Append links to every listed direct child page after this page\'s authored content.'),
 	aliases: z.array(pageAlias)
 		.min(1)
 		.refine((values) => new Set(values).size === values.length, 'Page aliases must be unique within the page.')
@@ -237,8 +227,10 @@ const sitewideFooter = z.object({
 }).strict().describe('Site-wide footer content.');
 
 const configShape = {
+	sourceFormat: z.literal(2).describe('Source format 2: page directories use slugs and sibling order lives in navigation.order frontmatter. Convert older sites before setting this value.'),
 	url: z.string().url().describe('Absolute public URL for the built site.'),
 	language: z.string().regex(supportedLocaleTagPattern).optional().describe('Site language tag selecting one complete built-in Norna interface language; the default is en.'),
+	verificationFiles: z.array(z.string().refine(isVerificationFilename, 'Use one verification filename outside Norna’s reserved and recognized paths.')).optional().describe('Exact filenames in public/ that verify ownership with an external service. Published unchanged at the site root. .well-known/ files need no declaration.'),
 	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.'),
@@ -251,9 +243,9 @@ const siteShape = {
 };
 
 const themeVisualShape = {
-	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
+	preset: themePreset.optional().describe('Select a new visual base, discarding all inherited theme values. Required in root/tree-theme.yaml; omit elsewhere to modify inherited values. Even the same preset starts a new base.'),
 	appearance: themeAppearance.optional(),
-	corners: cornerTreatment.optional().describe('Site-wide corner treatment. Omit this to use the selected preset.'),
+	corners: cornerTreatment.optional().describe('Corner treatment. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
 	blocks: themeBlocks.optional(),
@@ -262,44 +254,29 @@ const themeVisualShape = {
 	sections: themeSections.optional(),
 };
 
-const pageThemeShape = {
-	layout: pageThemeLayout.optional(),
-	images: themeImages.optional(),
-	sections: pageThemeSections.optional(),
-};
-
 const sitewideShape = {
 	logo: sitewideLogo.optional(),
 	banners: banners.describe('Site-wide dismissible notices.'),
 	footer: sitewideFooter.optional().describe('Site-wide footer content.'),
 };
 
-const categoryShape = {
-	label: z.string().trim().min(1).describe('Navigation label for a group of child pages without an authored page body.'),
-};
-
 export const schemaTopLevelKeys = Object.freeze({
 	config: Object.freeze(Object.keys(configShape)),
-	category: Object.freeze(Object.keys(categoryShape)),
 	content: Object.freeze(Object.keys(siteShape)),
 	sitewide: Object.freeze(Object.keys(sitewideShape)),
 	theme: Object.freeze(Object.keys(themeVisualShape)),
-	pageTheme: Object.freeze(Object.keys(pageThemeShape)),
+	pageTheme: Object.freeze(Object.keys(themeVisualShape)),
 });
 
 export const configSchema = z.object(configShape).strict()
 	.describe('Technical settings for one Norna site. Additional pages cannot provide technical configuration.');
-export const categorySchema = z.object(categoryShape).strict()
-	.describe('A navigation group without an authored page body. Opening its URL redirects when its first listed direct child is a page; otherwise it shows a generated child list.');
 export const siteSchema = z.object(siteShape).strict()
 	.describe('Frontmatter for a homepage or additional page content.md file.');
 export const themeVisualSchema = z.object(themeVisualShape).strict()
-	.describe('Site-wide visual identity and default page presentation. Presets may be selected only in the root theme.');
-export const pageThemeSchema = z.object(pageThemeShape).strict()
-	.refine(
-		(value) => value.layout !== undefined || value.images !== undefined || value.sections !== undefined,
-		'Specify layout, images, sections, or a combination of them.',
-	)
-	.describe('Limited page presentation overrides inherited by descendant pages. Site colors, corners, typography, content-block defaults and navigation remain global.');
+	.describe('Visual settings for this page and its descendants. Omit preset to modify inherited values; an explicit preset replaces the complete inherited base, even when the preset name is unchanged.');
+export const rootThemeSchema = z.object({ ...themeVisualShape, preset: themePreset }).strict()
+	.describe('Required root/tree-theme.yaml. Select a preset for the site, then add the visual settings you want to override.');
+export const pageThemeSchema = z.object(themeVisualShape).strict()
+	.describe('Visual settings for this page only. Omit preset to modify the active tree theme; an explicit preset replaces that base. Descendants keep their tree theme.');
 export const sitewideSchema = z.object(sitewideShape).strict()
 	.describe('Editorial content and optional navigation logo display settings shared by every page.');

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

@@ -150,15 +150,17 @@ const addSitewideLogoHelp = (jsonSchema) => {
 
 const addConfigHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
-		yamlExample('url: https://example.com/'),
-		'`config.yaml` contains the few technical settings shared by the complete site.',
+		yamlExample('sourceFormat: 2\nurl: https://example.com/'),
+		'`site-config/settings.yaml` contains the few technical settings shared by the complete site.',
 		documentationLink('Configuration reference', 'configuration.md'),
 	].join('\n\n');
+	addFieldHelp(jsonSchema, 'sourceFormat', 'sourceFormat: 2', 'pages.md', 'page-source-layout');
 	addHelp(jsonSchema, 'url', [
 		yamlExample('url: https://example.com/'),
 		'The absolute public URL. Its path also determines the base path for generated links and assets.',
 		documentationLink('Public URL reference', 'configuration.md', 'url'),
 	], ['https://example.com/', 'https://owner.github.io/repository-name/']);
+	addFieldHelp(jsonSchema, 'verificationFiles', 'verificationFiles:\n  - google-example.html', 'public-files.md', 'verification-files');
 	addHelp(jsonSchema, 'language', [
 		yamlExample('language: en-GB'),
 		'Sets the language of the complete site and selects the matching built-in Norna interface text. Regional tags are preserved. The default is `en`; editorial Markdown is not translated.',
@@ -283,7 +285,7 @@ const addThemeHelp = (jsonSchema) => {
 	], presentationPaletteNames);
 	addHelp(jsonSchema, 'appearance', [
 		yamlExample('appearance:\n  default: system'),
-		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to follow the visitor\'s system preference.',
+		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to keep the inherited or preset value.',
 		documentationLink('Appearance', 'theme.md', 'appearance'),
 	]);
 	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
@@ -463,49 +465,10 @@ const addThemeHelp = (jsonSchema) => {
 	})]);
 };
 
-const addPageThemeHelp = (jsonSchema) => {
-	jsonSchema.markdownDescription = [
-		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'A limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	].join('\n\n');
-	addHelp(jsonSchema, 'layout', [
-		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'Adjusts body-text line length and vertical content spacing for pages below this directory.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	]);
-	addFieldHelp(jsonSchema, 'layout.textWidth', 'layout:\n  textWidth: narrow', 'theme.md', 'page-themes', ['narrow', 'normal', 'wide']);
-	addFieldHelp(jsonSchema, 'layout.contentSpacing', 'layout:\n  contentSpacing: compact', 'theme.md', 'page-themes', ['compact', 'normal', 'spacious']);
-	addHelp(jsonSchema, 'images', [
-		yamlExample('images:\n  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'],
-		['images.maxAvailableWidthPercent.mobile', 'images:\n  maxAvailableWidthPercent:\n    mobile: 100'],
-		['images.maxAvailableHeightPercent', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68'],
-		['images.maxAvailableHeightPercent.desktop', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74'],
-		['images.maxAvailableHeightPercent.mobile', 'images:\n  maxAvailableHeightPercent:\n    mobile: 68'],
-	];
-	for (const [propertyPath, example] of imageFields) {
-		addFieldHelp(jsonSchema, propertyPath, example, 'theme.md', 'image-sizing');
-	}
-	addHelp(jsonSchema, 'sections', [
-		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Adjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.',
-		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
-	]);
-	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'accented']);
-};
-
 const addSitewideHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('footer:\n  copyrightMessage: Copyright Example Owner.'),
-		'`sitewide-content.yaml` optionally defines banners, footer content, and logo display settings shared by every page.',
+		'`site-config/shared-content.yaml` optionally defines banners, footer content, and logo display settings shared by every page.',
 		documentationLink('Site-wide content reference', 'sitewide-content.md'),
 	].join('\n\n');
 	addSitewideLogoHelp(jsonSchema);
@@ -583,9 +546,10 @@ const addContentHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'page.description', [
 		yamlExample('page:\n  description: About this project.'),
-		'A page-specific description used in metadata and social previews. Generated child-page and category lists can show it beside the page title; it is not inserted into the page body.',
+		'A page-specific description used in metadata and social previews. Generated child-page lists can show it beside the page title; it is not inserted into the page body.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	], ['About this project.']);
+	addFieldHelp(jsonSchema, 'page.listChildren', 'page:\n  listChildren: true', 'pages.md', 'list-child-pages', [true, false]);
 	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.',
@@ -601,31 +565,23 @@ const addContentHelp = (jsonSchema) => {
 		'Optionally excludes an additional page from site navigation without removing its public URL.',
 		documentationLink('Site navigation reference', 'pages.md', 'navigation'),
 	]);
+	addFieldHelp(jsonSchema, 'navigation.order', 'navigation:\n  order: 1000', 'pages.md', 'navigation');
 	addFieldHelp(jsonSchema, 'navigation.listed', 'navigation:\n  listed: false', 'pages.md', 'navigation', [true, false]);
 };
 
-const addCategoryHelp = (jsonSchema) => {
-	jsonSchema.markdownDescription = [
-		yamlExample('label: Guides'),
-		'`category.yaml` groups child pages without editorial content. Its URL opens the first listed direct page, or a generated child list when the first child is a category.',
-		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
-	].join('\n\n');
-	addHelp(jsonSchema, 'label', [
-		yamlExample('label: Guides'),
-		'The category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.',
-		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
-	]);
-};
-
 export const applySchemaEditorMetadata = (filename, jsonSchema) => {
 	addValueDescriptions(jsonSchema);
-	if (filename === 'category.schema.json') addCategoryHelp(jsonSchema);
 	if (filename === 'config.schema.json') {
 		addLanguageSuggestions(jsonSchema);
 		addConfigHelp(jsonSchema);
 	}
-	if (filename === 'theme.schema.json') addThemeHelp(jsonSchema);
-	if (filename === 'page-theme.schema.json') addPageThemeHelp(jsonSchema);
+	if (['root-theme.schema.json', 'theme.schema.json', 'page-theme.schema.json'].includes(filename)) {
+		addThemeHelp(jsonSchema);
+		jsonSchema.markdownDescription = [yamlExample(filename === 'root-theme.schema.json' ? 'preset: documentation' : 'layout:\n  textWidth: wide'), jsonSchema.description, documentationLink('Theme inheritance', 'theme.md', 'page-themes')].join('\n\n');
+		addHelp(jsonSchema, 'preset', [yamlExample('preset: documentation'),
+			'Selects a new base and discards inherited theme values, even when the preset name is unchanged. Required in root/tree-theme.yaml. Omit in other theme files to modify inherited values.',
+			documentationLink('Theme inheritance', 'theme.md', 'page-themes'), documentationLink('Preset reference', 'theme.md', 'theme-presets')]);
+	}
 	if (filename === 'sitewide-content.schema.json') addSitewideHelp(jsonSchema);
 	if (filename === 'content-frontmatter.schema.json') addContentHelp(jsonSchema);
 	return jsonSchema;

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

@@ -26,7 +26,7 @@ export const schemaValueDefinitions = Object.freeze([
 		automatic: option('Automatic', 'Choose one site-wide navigation presentation from the listed page hierarchy. This is the default.'),
 		sections: option('Sections', 'Keep a one-page site title and its H2 sections in sticky page navigation.'),
 		top: option('Top', 'Keep top-level pages in the global row and give the current page section navigation when needed.'),
-		tree: option('Tree', 'Keep top-level areas global and add a persistent left page tree. Deep branches can add a right H2/H3 contents rail.'),
+		tree: option('Tree', 'Group destinations in menus and show the selected group’s pages and H2 links in a left tree.'),
 	}),
 	definition(['vscode'], {
 		vscode: option('Visual Studio Code', 'Open the current page source in the locally installed Visual Studio Code application.'),

package/scripts/lib/site-content.mjs

@@ -22,9 +22,6 @@ const frontmatterDelimiterRegex = /^---\s*$/;
 const knownConfigTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.config);
 const knownContentTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.content);
 const knownThemeTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.theme);
-const knownPageThemeTopLevelFrontmatterKeys = new Set(
-	schemaTopLevelKeys.pageTheme,
-);
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
 	'align',
@@ -57,6 +54,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'listed',
 	'logo',
 	'lineHeight',
+	'listChildren',
 	'maxAvailableHeightPercent',
 	'maxAvailableWidthPercent',
 	'mobile',
@@ -152,30 +150,21 @@ 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 image-stack or image-carousel blocks in the Markdown body.';
+			fix = 'Put local image references in the Markdown body, using images/name.jpg or an image-stack or image-carousel block.';
 		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
-			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
+			fix = `Move "${key}:" to site-config/site-theme.yaml. Visual settings do not belong in content frontmatter.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
-			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
-			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
+			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in site-config/settings.yaml.`;
+			fix = 'Set the navigation mode under "navigation:" in site-config/settings.yaml.';
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'shape') {
-			message = fileKind === 'page theme'
-				? `Frontmatter line ${lineNumber}: "shape" was replaced by the site-wide "corners" setting, which page themes cannot override.`
-				: `Frontmatter line ${lineNumber}: "shape" was replaced by "corners". Use "square" or replace the old "soft" value with "rounded".`;
-			fix = fileKind === 'page theme'
-				? 'Remove "shape:" from this page theme. Set "corners: square" or "corners: rounded" in the root theme.yaml when an override is needed.'
-				: 'Replace "shape:" with "corners:". Use "square" or replace the old "soft" value with "rounded".';
+			message = `Frontmatter line ${lineNumber}: "shape" was replaced by "corners".`;
+			fix = 'Use "corners: square" or "corners: rounded"; replace the old "soft" value with "rounded".';
 		} 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:".';
+			fix = 'Replace "colorMode:" with "appearance:".';
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'readerControls') {
 			message = `Frontmatter line ${lineNumber}: Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation.`;
 			fix = 'Remove "readerControls:". Use "appearance.default" for the initial Appearance; reading width is always available and tree navigation provides Focus reading.';
-		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'corners', 'palette', 'typography'].includes(key)) {
-			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
-			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: ${fileKind} may not define navigation logo settings. Optional logo display settings belong under "logo:" in ${sitewideContentLabel}.`;
 			fix = `Move only the logo display settings under "logo:" in ${sitewideContentLabel}; the homepage Markdown H1 supplies navigation text and logo alternative text.`;
@@ -223,12 +212,6 @@ export const validateThemeYamlStructure = (frontmatter, addIssue) =>
 		fileKind: 'theme',
 	});
 
-export const validatePageThemeYamlStructure = (frontmatter, addIssue) =>
-	validateFrontmatterStructure(frontmatter, addIssue, {
-		knownTopLevelFrontmatterKeys: knownPageThemeTopLevelFrontmatterKeys,
-		fileKind: 'page theme',
-	});
-
 export const validateSitewideYamlStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownSitewideTopLevelFrontmatterKeys,

package/scripts/lib/site-conventions.mjs

@@ -1 +1,19 @@
-export const homePageDirectory = '000-home';
+import path from 'node:path';
+
+// Logical identities stay independent of the physical root/ directory.
+export const homePageDirectory = '.';
+export const legacyHomePageDirectory = '000-home';
+
+export const getSiteSourcePaths = (siteRoot) => {
+	const root = path.join(siteRoot, 'root');
+	return { root, pages: path.join(root, 'pages'), content: path.join(root, 'content.md'),
+		images: path.join(root, 'images'), theme: path.join(root, 'tree-theme.yaml') };
+};
+
+export const getPageSourceDirectory = (pageDirectory) => (
+	pageDirectory === homePageDirectory ? 'root' : `root/pages/${pageDirectory}`
+);
+
+export const getPageImageSourceKey = (pageDirectory, image) => (
+	[getPageSourceDirectory(pageDirectory), 'images', image].filter(Boolean).join('/')
+);