@janga/norna 0.7.28 → 0.7.30

package/scripts/lib/page-markdown.mjs

@@ -1,3 +1,4 @@
+import { extractMarkdownImageReferences, markdownImageDiagnostic } from './markdown-images.mjs';
 import { getCodeFenceMetadataDiagnostics } from './code-fence-metadata.mjs';
 import { parseContentTabs } from './content-tabs.mjs';
 import { getDetailsHeadingDiagnostics } from './details-headings.mjs';
@@ -11,7 +12,6 @@ import {
 } from './markdown-links.mjs';
 import {
 	extractInlineNoteDiagnostics,
-	extractMarkdownImageReferences,
 	extractNornaMarkdownBlockDiagnostics,
 	getNornaBlockImageReferences,
 	nornaBlockTypes,
@@ -191,6 +191,7 @@ const createRegion = ({
 	tableErrors,
 	tabResult,
 	pageNotes,
+	imageReferences,
 }) => {
 	const endOffset = nextHeading?.index ?? source.length;
 	const markdown = source.slice(heading.index, endOffset).trimEnd();
@@ -201,10 +202,7 @@ const createRegion = ({
 	});
 	const inRegion = (offset) => offset >= heading.index && offset < endOffset;
 	const fieldNoteErrors = getStructuredSidenoteDiagnostics(blockResult.blocks, { label, regionOffset: heading.index });
-	const markdownImages = extractMarkdownImageReferences(markdown).map((reference) => ({
-		...reference,
-		line: regionLineOffset + reference.line,
-	}));
+	const markdownImages = imageReferences.filter((reference) => inRegion(reference.range.start));
 	const regionHeadings = headings.filter((candidate) => (
 		candidate.index >= heading.index
 		&& candidate.index < endOffset
@@ -226,7 +224,7 @@ const createRegion = ({
 		kind: heading.depth === 1 ? 'page-intro' : 'section',
 		bodyLine: heading.line,
 		line: lineOffset + heading.line,
-		managedImages: getNornaBlockImageReferences(blockResult.blocks),
+		managedImages: [...getNornaBlockImageReferences(blockResult.blocks), ...markdownImages.filter((reference) => reference.kind === 'managed')],
 		markdown,
 		markdownImages,
 		notes: pageNotes.notes.filter((note) => inRegion(note.referenceOffset)),
@@ -246,6 +244,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	const tabResult = parseContentTabs(source, { label, lineOffset });
 	const pageNotes = extractInlineNoteDiagnostics(source, { label, lineOffset, tabResult });
 	const { headings, tree } = await getMarkdownHeadings(tabResult.maskedSource);
+	const imageReferences = extractMarkdownImageReferences({ source, tree, lineOffset });
 	const detailsDiagnostics = getDetailsHeadingDiagnostics(tree, { source: tabResult.maskedSource, label, lineOffset });
 	const calloutErrors = getSemanticCalloutDiagnostics(tree, { label, lineOffset });
 	const codeFenceErrors = getCodeFenceMetadataDiagnostics(tree, {
@@ -271,6 +270,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		pageNotes,
 		tableErrors,
 		tabResult,
+		imageReferences,
 	}));
 	const headingIssues = getHeadingIdentifierIssues(headings);
 	const headingDiagnostics = getHeadingDiagnostics(headings, lineOffset);
@@ -346,6 +346,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 	return {
 		blocks,
 		diagnostics: [
+			...imageReferences.filter((reference) => reference.kind === 'invalid').map((reference) => markdownImageDiagnostic(reference, label)),
 			...detailsDiagnostics,
 			...structureDiagnostics,
 			...headingDiagnostics,
@@ -363,7 +364,7 @@ export const parsePageMarkdown = async (markdown, options = {}) => {
 		lineOffset,
 		links,
 		managedImages: regions.flatMap((region) => region.managedImages),
-		markdownImages: regions.flatMap((region) => region.markdownImages),
+		markdownImages: imageReferences,
 		navigationHeadings,
 		notes: regions.flatMap((region) => region.notes),
 		noteDiagnostics,
@@ -395,8 +396,11 @@ export const parsePageMarkdownSource = async (source, options = {}) => {
 		};
 	};
 
+	const mapImage = (reference) => reference.blockType === 'markdown-image' ? { ...reference, range: toOriginalRange(reference.range), targetRange: toOriginalRange(reference.targetRange) } : reference;
 	return {
 		...model,
+		markdownImages: model.markdownImages.map(mapImage),
+		managedImages: model.managedImages.map(mapImage),
 		bodyOffset: normalization.originalOffsets[split.bodyOffset] ?? split.bodyOffset,
 		frontmatter: split.frontmatter,
 		frontmatterUnclosed: split.frontmatterUnclosed,

package/scripts/lib/page-model.mjs

@@ -1,26 +1,14 @@
 import { homePageDirectory } from './site-conventions.mjs';
 
-export const pageDirectoryPattern = /^(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+export const pageDirectoryPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 const pageEntryPathSeparator = '--';
 
 export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
-	const match = pageDirectory.match(pageDirectoryPattern);
-
-	if (!match) {
-		throw new Error(
-			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. Page ids may contain only lowercase letters, numbers, and single hyphens.`,
-		);
-	}
-	if (match[1] === '000') {
-		throw new Error(`Invalid ${label} "${pageDirectory}". Child page orders must be 001–999. The homepage is root/content.md in the site container.`);
+	if (!pageDirectoryPattern.test(pageDirectory)) {
+		throw new Error(`Invalid ${label} "${pageDirectory}". Page directories must use a slug with lowercase letters, numbers, and single hyphens, for example getting-started.`);
 	}
-
-	return {
-		pageDirectory,
-		pageOrder: Number.parseInt(match[1], 10),
-		pageId: match[2],
-	};
+	return { pageDirectory, pageOrder: null, pageId: pageDirectory };
 };
 
 const normalizePageDirectoryPath = (pageDirectoryPath) => pageDirectoryPath.replaceAll('\\', '/');
@@ -30,7 +18,7 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 	if (normalizedPath === homePageDirectory) {
 		return {
 			pageDirectory: homePageDirectory, pageDirectories: [], pageId: 'home',
-			pageIds: [], pageOrder: 0, pageOrders: [], pagePath: '',
+			pageIds: [], pageOrder: 0, pagePath: '',
 			parentPagePath: null, depth: 0,
 		};
 	}
@@ -38,7 +26,7 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 
 	if (!normalizedPath || normalizedPath.startsWith('/') || normalizedPath.endsWith('/') || segments.length % 2 === 0) {
 		throw new Error(
-			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form NNN-page-id/pages/NNN-child-id.`,
+			`Invalid ${label} "${pageDirectoryPath}". Nested pages must use the form page-id/pages/child-id.`,
 		);
 	}
 
@@ -57,7 +45,6 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 	}
 
 	const pageIds = pageDirectories.map(({ pageId }) => pageId);
-	const pageOrders = pageDirectories.map(({ pageOrder }) => pageOrder);
 	const currentPage = pageDirectories.at(-1);
 
 	return {
@@ -66,7 +53,6 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 		pageId: currentPage.pageId,
 		pageIds,
 		pageOrder: currentPage.pageOrder,
-		pageOrders,
 		pagePath: pageIds.join('/'),
 		// Navigation projects the root's children as top-level entries.
 		parentPagePath: pageIds.length > 1
@@ -78,11 +64,11 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 
 export const encodePageDirectoryPath = (pageDirectoryPath) => {
 	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
-	return pageDirectories.length ? pageDirectories.join(pageEntryPathSeparator) : 'root';
+	return pageDirectories.length ? pageDirectories.join(pageEntryPathSeparator) : '~home';
 };
 
 export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path') => {
-	if (pageEntryPath === 'root') return homePageDirectory;
+	if (pageEntryPath === '~home') return homePageDirectory;
 	const pageDirectories = pageEntryPath.split(pageEntryPathSeparator);
 	if (pageDirectories.some((pageDirectory) => !pageDirectory)) {
 		throw new Error(`Invalid ${label} "${pageEntryPath}".`);

package/scripts/lib/page-move-apply.mjs

@@ -1,10 +1,11 @@
+import { assertRenumberingAllowed } from './page-order.mjs';
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getSiteLinkGraph } from './site-link-graph.mjs';
 import { getSiteStructure } from './site-structure.mjs';
 
-const writeFileAtomically = async (filePath, source, mode) => {
+export const writeFileAtomically = async (filePath, source, mode) => {
 	const temporaryPath = path.join(
 		path.dirname(filePath),
 		`.${path.basename(filePath)}.norna-${process.pid}-${randomUUID()}.tmp`,
@@ -31,7 +32,7 @@ const assertSourcesUnchanged = async (plan) => {
 
 const assertFinalSite = async (siteRoot, generatedRoutes) => {
 	const structure = await getSiteStructure({ siteRoot });
-	const graph = await getSiteLinkGraph({ siteStructure: structure, publicDir: path.join(siteRoot, 'public'), generatedRoutes });
+	const graph = await getSiteLinkGraph({ siteRoot, siteStructure: structure, publicDir: path.join(siteRoot, 'public'), generatedRoutes });
 	const errors = graph.diagnostics.filter(({ severity }) => severity === 'error');
 	if (errors.length === 0) return;
 	throw new Error([
@@ -43,7 +44,8 @@ const assertFinalSite = async (siteRoot, generatedRoutes) => {
 	].join('\n'));
 };
 
-export const applyPageMovePlan = async (plan, { siteRoot, generatedRoutes, renameDirectory = rename }) => {
+export const applyPageMovePlan = async (plan, { siteRoot, generatedRoutes, renameDirectory = rename, writeSource = writeFileAtomically, allowRenumber = false }) => {
+	assertRenumberingAllowed(plan.orderChanges ?? [], allowRenumber);
 	await assertSourcesUnchanged(plan);
 	let collectionCreated = false;
 	let directoryMoved = false;
@@ -67,7 +69,7 @@ export const applyPageMovePlan = async (plan, { siteRoot, generatedRoutes, renam
 		}
 
 		for (const change of plan.fileChanges) {
-			await writeFileAtomically(change.finalPath, change.updatedSource, change.mode);
+			await writeSource(change.finalPath, change.updatedSource, change.mode);
 			fileWritten = true;
 		}
 		await assertFinalSite(siteRoot, generatedRoutes);

package/scripts/lib/page-move-plan.mjs

@@ -1,3 +1,6 @@
+import { comparePageOrder, parsePageOrder, planPageOrder, describeRenumbering } from './page-order.mjs';
+import { setPageOrder } from './page-order-source.mjs';
+import { attachmentPathname, encodeAttachmentPath, localAttachmentName } from './page-attachments.mjs';
 import { access, constants, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import {
@@ -38,15 +41,6 @@ const replaceFilePathPrefix = (filePath, fromDirectory, toDirectory) => (
 	path.join(toDirectory, path.relative(fromDirectory, filePath))
 );
 
-const getNextOrder = (siblings) => {
-	const highestOrder = siblings.reduce((highest, node) => Math.max(highest, node.pageOrder), 0);
-	const nextOrder = Math.floor(highestOrder / 10) * 10 + 10;
-	if (nextOrder > 999) {
-		throw new Error('No automatic page order remains below 1000. Reorder the destination siblings or pass --order.');
-	}
-	return nextOrder;
-};
-
 const getTargetSuffix = (target) => {
 	const queryIndex = target.indexOf('?');
 	const fragmentIndex = target.indexOf('#');
@@ -201,6 +195,11 @@ const getResolvedReferenceIntent = ({
 		};
 	}
 
+	if (resolution?.kind === 'attachment') {
+		const owner = movedCurrentToNew.get(resolution.file.ownerPathname) ?? resolution.file.ownerPathname;
+		return { kind: 'attachment', lookupPathname: attachmentPathname(owner, resolution.file.filename), owner, filename: resolution.file.filename };
+	}
+
 	if (resolution?.kind === 'public-file') {
 		return { kind: 'public-file', lookupPathname: target.pathname };
 	}
@@ -259,7 +258,7 @@ const getReferenceIntent = ({
 	const sourceMapping = mappingByCurrentPathname.get(reference.sourcePage.pathname);
 	if (!sourceMapping || sourceMapping.oldPathname === sourceMapping.currentPathname) return currentIntent;
 
-	const oldTarget = resolveInternalTarget(reference.targetSource, sourceMapping.oldPathname);
+	const oldTarget = resolveInternalTarget(reference.targetSource, sourceMapping.oldPathname, graph.siteUrl);
 	const oldIntent = getTargetIntent({
 		graph,
 		movedCurrentToNew,
@@ -311,8 +310,9 @@ const createReferenceChanges = ({ graph, mappings }) => {
 
 		const sourcePathname = movedCurrentToNew.get(reference.sourcePage.pathname)
 			?? reference.sourcePage.pathname;
-		const resolvedAfterMove = resolveInternalTarget(reference.targetSource, sourcePathname);
-		const stillResolves = resolvedAfterMove.kind === 'internal'
+		const originalTarget = intent.kind === 'attachment' ? reference.sourceTarget ?? reference.targetSource : reference.targetSource;
+		const resolvedAfterMove = resolveInternalTarget(originalTarget, sourcePathname, graph.siteUrl);
+		const stillResolves = intent.kind === 'attachment' ? (localAttachmentName(originalTarget) === intent.filename && sourcePathname === intent.owner || resolvedAfterMove.pathname === intent.lookupPathname) : resolvedAfterMove.kind === 'internal'
 			&& (intent.kind === 'public-file'
 				? resolvedAfterMove.pathname === intent.lookupPathname
 				: resolvedAfterMove.pageLookupPathname === intent.lookupPathname);
@@ -324,7 +324,7 @@ const createReferenceChanges = ({ graph, mappings }) => {
 			);
 		}
 
-		const value = `${intent.lookupPathname}${getTargetSuffix(reference.targetSource)}`;
+		const value = `${reference.target.absolutePrefix ?? ''}${intent.kind === 'attachment' ? encodeAttachmentPath(intent.lookupPathname) : intent.lookupPathname}${getTargetSuffix(reference.targetSource)}`;
 		const key = `${reference.sourceContentFile.contentPath}:${reference.targetRange.start}:${reference.targetRange.end}`;
 		const existing = changeKeys.get(key);
 		if (existing && existing.to !== value) {
@@ -360,6 +360,7 @@ export const createPageMovePlan = async ({
 	graph,
 	generatedRoutes,
 	order = null,
+	siblingOrderChanges = [],
 	preserveAliases = true,
 	publicFiles,
 	sitePagesDir,
@@ -405,6 +406,7 @@ export const createPageMovePlan = async ({
 	let destinationCollectionDirectory = null;
 	let destinationCollectionExists = true;
 	let virtualNodes = siteStructure.nodes;
+	let orderChanges = siblingOrderChanges;
 
 	if (mode === 'move') {
 		const destinationParentPath = getParentPagePath(destination.pagePath);
@@ -419,22 +421,23 @@ export const createPageMovePlan = async ({
 		}
 
 		const destinationSiblings = siteStructure.nodes.filter((node) => (
-			node.parentPagePath === destinationParentPath
+			!node.isHome && node.parentPagePath === destinationParentPath
 			&& !isPathInSubtree(node.pagePath, source.pagePath)
 		));
 		const sameParent = sourceNode.parentPagePath === destinationParentPath;
-		destinationOrder = order ?? (sameParent ? sourceNode.pageOrder : getNextOrder(destinationSiblings));
-		if (destinationSiblings.some((node) => node.pageOrder === destinationOrder)) {
-			throw new Error(`Destination order ${String(destinationOrder).padStart(3, '0')} is already used below ${destinationParentPath ? `/${destinationParentPath}/` : '/'}.`);
+		if (order !== null) destinationOrder = parsePageOrder(order, '--order');
+		else if (!sameParent) {
+			const insertion = planPageOrder(destinationSiblings.sort(comparePageOrder), destinationSiblings.length);
+			destinationOrder = insertion.order;
+			orderChanges = insertion.orderChanges;
 		}
-
 		const destinationSlug = destination.pagePath.split('/').at(-1);
 		destinationCollectionDirectory = destinationParent
 			? path.join(destinationParent.nodeDir, 'pages')
 			: sitePagesDir;
 		destinationDirectory = path.join(
 			destinationCollectionDirectory,
-			`${String(destinationOrder).padStart(3, '0')}-${destinationSlug}`,
+			destinationSlug,
 		);
 		if (await exists(destinationDirectory)) {
 			throw new Error(`Destination directory ${destinationDirectory} already exists.`);
@@ -536,6 +539,11 @@ export const createPageMovePlan = async ({
 			}
 		}
 
+		const siblingChange = orderChanges.find(change => change.node.contentPath === contentPath);
+		if (siblingChange) updatedSource = setPageOrder(updatedSource, siblingChange.newOrder, contentPath);
+		if (mode === 'move' && contentPath === activeRoot.contentPath && destinationOrder !== activeRoot.pageOrder) {
+			updatedSource = setPageOrder(updatedSource, destinationOrder, contentPath);
+		}
 		updatedSources.set(contentPath, updatedSource);
 		if (updatedSource !== page.document.fullSource) {
 			const fileStat = await stat(contentPath);
@@ -576,7 +584,14 @@ export const createPageMovePlan = async ({
 		nodes: virtualNodes,
 		warnings: siteStructure.warnings,
 	};
+	const virtualAttachments = { diagnostics: graph.attachments?.diagnostics ?? [], files: (graph.attachments?.files ?? []).map(file => {
+		const mapping = mappings.find(entry => entry.currentPathname === file.ownerPathname);
+		if (!mapping) return file;
+		return { ...file, ownerPathname: mapping.newPathname, pathname: attachmentPathname(mapping.newPathname, file.filename) };
+	}) };
 	const virtualGraph = createSiteLinkGraph({
+		siteUrl: graph.siteUrl,
+		attachments: virtualAttachments,
 		pageDocuments: virtualPageDocuments,
 		publicFiles,
 		siteStructure: virtualStructure,
@@ -602,6 +617,8 @@ export const createPageMovePlan = async ({
 
 	return {
 		aliasChanges,
+		generatedRoutes,
+		orderChanges,
 		destinationCollectionDirectory,
 		destinationCollectionExists,
 		destinationDirectory,
@@ -636,6 +653,7 @@ export const formatPageMovePlan = (plan, displayPath) => {
 	for (const change of plan.linkChanges) {
 		lines.push(`- ${change.contentLabel} line ${change.line}: ${change.from} -> ${change.to}`);
 	}
+	if (plan.orderChanges?.length) lines.push('', describeRenumbering(plan.orderChanges, displayPath));
 	lines.push('', 'Aliases:');
 	if (!plan.preserveAliases) lines.push('- skipped by --no-aliases');
 	else if (plan.aliasChanges.length === 0) lines.push('- none needed');

package/scripts/lib/page-order-source.mjs

@@ -0,0 +1,22 @@
+import { readFile, stat } from 'node:fs/promises';
+import { splitSiteFile } from './site-content.mjs';
+import { changeYamlField } from './yaml-source-edit.mjs';
+import { parsePageOrder } from './page-order.mjs';
+
+export const setPageOrder = (source, order, label) => {
+	parsePageOrder(order);
+	const eol = source.includes('\r\n') ? '\r\n' : '\n';
+	const { frontmatter, frontmatterBody, body } = splitSiteFile(source, label);
+	try {
+		const yaml = changeYamlField(frontmatterBody, ['navigation', 'order'], order ?? undefined, eol);
+		return frontmatter ? `---${eol}${yaml.replace(/\r?\n$/, '')}${eol}---${eol}${body}`
+			: `---${eol}${yaml}---${eol}${eol}${source}`;
+	} catch (error) { throw Object.assign(new Error(`Cannot set page order in ${label}. ${error.message}`), { sourcePath: label }); }
+};
+
+export const pageOrderFileChanges = async changes => Promise.all(changes.map(async ({ node, oldOrder, newOrder }) => {
+	const originalSource = await readFile(node.contentPath, 'utf8');
+	return { contentPath: node.contentPath, contentLabel: node.contentLabel, oldOrder, newOrder,
+		originalPath: node.contentPath, finalPath: node.contentPath, originalSource,
+		updatedSource: setPageOrder(originalSource, newOrder, node.contentPath), mode: (await stat(node.contentPath)).mode };
+}));

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/project-config.mjs

@@ -1,3 +1,4 @@
+import { assertSiteSourceFormat } from './site-source-format.mjs';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -34,6 +35,7 @@ const readSiteConfig = async () => {
 		throw error;
 	});
 
+	await assertSiteSourceFormat(siteDir);
 	return parseYamlConfig(source, siteConfigLabel, {
 		validateStructure: validateConfigYamlStructure,
 	});
@@ -423,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';
@@ -189,6 +190,7 @@ 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 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(
@@ -225,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.'),

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

@@ -150,15 +150,17 @@ const addSitewideLogoHelp = (jsonSchema) => {
 
 const addConfigHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
-		yamlExample('url: https://example.com/'),
+		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.',
@@ -563,6 +565,7 @@ 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]);
 };
 

package/scripts/lib/site-content.mjs

@@ -150,7 +150,7 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if (fileKind === 'content' && key === 'description') {
 			fix = 'Indent "description:" under "page:". The optional meta description belongs in the page object.';
 		} else if (fileKind === 'content' && key === 'images') {
-			fix = 'Put local image references in 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 site-config/site-theme.yaml. Visual settings do not belong in content frontmatter.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {