@janga/norna 0.7.28 → 0.7.30

package/scripts/lib/site-link-graph.mjs

@@ -1,4 +1,6 @@
-import { readdir, readFile } from 'node:fs/promises';
+import { publicFilePublication } from './publication-paths.mjs';
+import { getSiteAttachments, resolveAttachment, parseLocalAttachmentTarget, attachmentOutputIssues } from './page-attachments.mjs';
+import { readdir, readFile, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	createPageAliasModel,
@@ -11,6 +13,7 @@ import {
 	toPosixPath,
 } from './site-content.mjs';
 import {
+	siteDir as defaultSiteDir,
 	sitePagesLabel,
 	sitePublicDir,
 	sitePublicLabel,
@@ -18,11 +21,15 @@ import {
 import { getSiteNodePathname } from './site-page-urls.mjs';
 import { getSiteStructure } from './site-structure.mjs';
 import { createCategoryDestinationModel } from './category-destinations.mjs';
+import { parseYamlConfig } from './yaml-config.mjs';
+import { configSchema } from './schema-definitions.mjs';
 
 const internalUrlOrigin = 'https://norna.invalid';
 const externalSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
 
-const readPublicFiles = async (directory, relativeDirectory = '') => {
+const readPublicFiles = async (directory, settings = {}, relativeDirectory = '') => {
+	const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+	if (info && (!info.isDirectory() || info.isSymbolicLink())) throw new Error(`${directory} must be a regular public directory.`);
 	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') return [];
 		throw error;
@@ -30,19 +37,22 @@ const readPublicFiles = async (directory, relativeDirectory = '') => {
 	const files = [];
 
 	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+		if (entry.name === '.DS_Store' || entry.name.startsWith('._')) continue;
 		const relativePath = relativeDirectory
 			? path.join(relativeDirectory, entry.name)
 			: entry.name;
 		const entryPath = path.join(directory, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...await readPublicFiles(entryPath, relativePath));
+			publicFilePublication(toPosixPath(relativePath), settings, { directory: true });
+			files.push(...await readPublicFiles(entryPath, settings, relativePath));
 		} else if (entry.isFile()) {
 			files.push({
 				filePath: entryPath,
-				label: `${sitePublicLabel}/${toPosixPath(relativePath)}`,
-				pathname: `/${toPosixPath(relativePath)}`,
+				label: entryPath,
+				relativePath: toPosixPath(relativePath),
+				...publicFilePublication(toPosixPath(relativePath), settings),
 			});
-		}
+		} else throw new Error(`${entryPath} must be a regular public file. Symbolic links are not supported.`);
 	}
 
 	return files;
@@ -68,32 +78,47 @@ const getPageLookupPathname = (pathname) => {
 
 const isExternalTarget = (target) => target.startsWith('//') || externalSchemePattern.test(target);
 
-export const resolveInternalTarget = (target, sourcePathname) => {
-	if (isExternalTarget(target)) return { kind: 'external' };
+export const resolveInternalTarget = (target, sourcePathname, siteUrl) => {
+	const absolute = isExternalTarget(target);
+	if (absolute && (!siteUrl || !/^(?:https?:)?\/\//i.test(target))) return { kind: 'external' };
 
 	let url;
+	let siteBase;
 	try {
-		url = new URL(target, `${internalUrlOrigin}${sourcePathname}`);
+		siteBase = absolute ? new URL(siteUrl) : null;
+		url = new URL(target, siteBase ?? `${internalUrlOrigin}${sourcePathname}`);
 	} catch {
+		if (absolute) return { kind: 'external' };
 		return {
 			kind: 'invalid',
 			reason: 'The target is not a valid relative or site-relative URL.',
 		};
 	}
 
-	if (url.origin !== internalUrlOrigin) return { kind: 'external' };
+	if (url.origin !== (siteBase?.origin ?? internalUrlOrigin) || url.username || url.password) return { kind: 'external' };
 
 	try {
-		const pathname = decodePathname(url.pathname);
+		let pathname = decodePathname(url.pathname);
+		let absolutePrefix;
+		if (siteBase) {
+			const encodedBase = siteBase.pathname.replace(/\/?$/, '/');
+			const base = decodePathname(encodedBase);
+			if (pathname === base.slice(0, -1)) pathname = '/';
+			else if (pathname.startsWith(base)) pathname = '/' + pathname.slice(base.length);
+			else return { kind: 'external' };
+			absolutePrefix = (target.startsWith('//') ? `//${url.host}` : url.origin) + encodedBase.slice(0, -1);
+		}
 		const fragment = url.hash.length > 1 ? decodeFragment(url.hash.slice(1)) : '';
 		return {
 			kind: 'internal',
+			...(absolutePrefix ? { absolutePrefix } : {}),
 			fragment,
 			pageLookupPathname: getPageLookupPathname(pathname),
 			pathname,
 			query: url.search,
 		};
 	} catch (error) {
+		if (absolute) return { kind: 'external' };
 		return {
 			kind: 'invalid',
 			reason: error instanceof Error ? error.message : String(error),
@@ -146,9 +171,11 @@ const looksLikePublicFile = (pathname) => {
 };
 
 export const createSiteLinkGraph = ({
+	siteUrl,
 	siteStructure,
 	pageDocuments,
 	publicFiles = [],
+	attachments = { files: [], diagnostics: [] },
 	generatedRoutes,
 }) => {
 	const activeGeneratedRoutes = generatedRoutes ?? generatedSiteRoutes;
@@ -193,15 +220,28 @@ export const createSiteLinkGraph = ({
 
 	const references = [];
 	const referencesByTarget = new Map();
-	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics];
+	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics, ...attachments.diagnostics,
+		...attachmentOutputIssues({ files: attachments.files, pages, publicFiles, generatedRoutes: activeGeneratedRoutes })];
 
 	for (const page of pages) {
 		for (const sourceReference of page.document.links) {
-			const target = resolveInternalTarget(sourceReference.target, page.pathname);
+			const target = resolveInternalTarget(sourceReference.target, page.pathname, siteUrl);
 			if (target.kind === 'external') continue;
+			const attachment = target.kind === 'internal'
+				? resolveAttachment(sourceReference.target, page.pathname, attachments.files, target.pathname) : null;
+			// One origin/base path may also host independently built sites. Only
+			// adopt absolute URLs whose destination this source tree actually owns.
+			if (target.absolutePrefix && !attachment
+				&& !pagesByPathname.has(target.pageLookupPathname)
+				&& !aliasModel.aliasesByPathname.has(target.pageLookupPathname)
+				&& !publicFilesByPathname.has(target.pathname)
+				&& !categoriesByPathname.has(target.pageLookupPathname)
+				&& !generatedRoutesByPathname.has(target.pathname)
+				&& !generatedRoutesByPathname.has(target.pageLookupPathname)) continue;
 
 			const reference = {
 				...sourceReference,
+				sourceTarget: sourceReference.target,
 				sourceContentFile: page.contentFile,
 				sourcePage: page,
 				target,
@@ -222,6 +262,23 @@ export const createSiteLinkGraph = ({
 			if (!referencesByTarget.has(targetKey)) referencesByTarget.set(targetKey, []);
 			referencesByTarget.get(targetKey).push(reference);
 
+			const localAttachment = parseLocalAttachmentTarget(sourceReference.target);
+			if (attachment) {
+				const ambiguous = localAttachment?.prefix === '' && (publicFilesByPathname.has(target.pathname) || pagesByPathname.has(target.pageLookupPathname) || aliasModel.aliasesByPathname.has(target.pageLookupPathname));
+				if (ambiguous) {
+					reference.resolution = { kind: 'ambiguous-attachment' };
+					diagnostics.push(createIssue(reference, 'ambiguous-attachment', `Link "${sourceReference.target}" could identify a page/public file or a local attachment.`, `Use ${attachment.pathname} for the attachment or an explicit site-relative page/public link.`));
+				} else reference.resolution = { kind: 'attachment', file: attachment, pathname: attachment.pathname };
+				continue;
+			}
+
+			if (localAttachment?.prefix) {
+				const expectedPath = path.join(path.dirname(page.contentFile.contentPath), 'downloads', localAttachment.filename);
+				reference.resolution = { kind: 'missing-attachment', pathname: target.pathname };
+				diagnostics.push(createIssue(reference, 'missing-attachment', `Attachment "${sourceReference.target}" was not found at ${toPosixPath(expectedPath)}.`, 'Add the file to this page’s downloads/ folder or correct the link.'));
+				continue;
+			}
+
 			const targetPage = target.pageLookupPathname
 				? pagesByPathname.get(target.pageLookupPathname)
 				: null;
@@ -304,13 +361,19 @@ export const createSiteLinkGraph = ({
 				continue;
 			}
 
+			if (target.pathname.startsWith('/_norna/downloads/') && !target.pathname.endsWith('/')) {
+				reference.resolution = { kind: 'missing-attachment', pathname: target.pathname };
+				diagnostics.push(createIssue(reference, 'missing-attachment', `Attachment "${sourceReference.target}" does not exist.`, 'Add the file to its owning page’s downloads/ or correct the link.'));
+				continue;
+			}
+
 			if (looksLikePublicFile(target.pathname)) {
 				reference.resolution = { kind: 'missing-public-file', pathname: target.pathname };
 				diagnostics.push(createIssue(
 					reference,
 					'missing-public-file',
-					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to public file "${target.pathname}", but no matching file exists under ${sitePublicLabel}/.`,
-					`Add the file under ${sitePublicLabel}/ with the same relative path, or correct the link.`,
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to public file "${target.pathname}", but no matching file exists under ${sitePublicLabel}/ or the owning page’s downloads/.`,
+					'Use the published address of an allowed public image or technical file, or link to a page-owned attachment.',
 				));
 				continue;
 			}
@@ -327,6 +390,8 @@ export const createSiteLinkGraph = ({
 	}
 
 	return {
+		siteUrl,
+		attachments,
 		categoryModel,
 		aliasModel,
 		aliases: aliasModel.aliases,
@@ -342,7 +407,10 @@ export const createSiteLinkGraph = ({
 };
 
 export const getSiteLinkGraph = async (options = {}) => {
-	const siteStructure = options.siteStructure ?? await getSiteStructure();
+	const siteRoot = options.siteRoot ?? defaultSiteDir;
+	const siteStructure = options.siteStructure ?? await getSiteStructure({ siteRoot });
+	const settingsPath = path.join(siteRoot, 'site-config/settings.yaml');
+	const settings = parseYamlConfig(await readFile(settingsPath, 'utf8'), settingsPath, { schema: configSchema });
 	const [pageDocuments, publicFiles] = await Promise.all([
 		Promise.all(siteStructure.contentFiles.map(async (contentFile) => {
 			const source = await readFile(contentFile.contentPath, 'utf8');
@@ -353,15 +421,17 @@ export const getSiteLinkGraph = async (options = {}) => {
 				document: await parsePageMarkdownSource(source, { label: contentFile.contentLabel }),
 			};
 		})),
-		readPublicFiles(options.publicDir ?? sitePublicDir),
+		readPublicFiles(options.publicDir ?? path.join(siteRoot, 'public'), settings),
 	]);
 
 	return createSiteLinkGraph({
+		siteUrl: settings.url,
 		pageDocuments,
 		publicFiles,
 		siteStructure,
+		attachments: await getSiteAttachments(siteStructure),
 		generatedRoutes: options.generatedRoutes,
 	});
 };
 
-export const getSitePublicFiles = async (publicDir = sitePublicDir) => readPublicFiles(publicDir);
+export const getSitePublicFiles = async (publicDir = sitePublicDir, settings = {}) => readPublicFiles(publicDir, settings);

package/scripts/lib/site-node-create.mjs

@@ -1,3 +1,6 @@
+import { comparePageOrder, parsePageOrder, planPageOrder, assertRenumberingAllowed } from './page-order.mjs';
+import { pageOrderFileChanges } from './page-order-source.mjs';
+import { writeFileAtomically } from './page-move-apply.mjs';
 import { getSiteSourcePaths } from './site-conventions.mjs';
 import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -9,17 +12,7 @@ import { siteSchema } from './schema-definitions.mjs';
 import { readEditorLinkState } from './editor-site-links.mjs';
 import { createPageAliasModel, assertPageAliasModel } from './page-aliases.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
-
-const parseOrder = (value) => {
-	if (!/^\d{1,3}$/.test(value)) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	const order = Number.parseInt(value, 10);
-	if (order < 1 || order > 999) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	return order;
-};
+import { publicationIssues } from './publication-paths.mjs';
 
 const normalizeParentPath = (value) => {
 	if (value === '/') return '';
@@ -33,15 +26,6 @@ const normalizeParentPath = (value) => {
 	return normalized;
 };
 
-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 sibling nodes before adding another one.');
-	}
-	return nextOrder;
-};
-
 export const escapeMarkdownHeading = (value) => value.replace(/([\\`*_[\]{}<>#])/g, '\\$1');
 
 const canonicalDirectory = async (directory) => realpath(directory).catch((error) => {
@@ -86,30 +70,40 @@ const resolveParent = async ({ nodes, parent, siteRoot, invocationDirectory }) =
 // Planning never writes. Callers must present this same destination before applying.
 export const planSiteNodeCreation = async ({
 	siteRoot, kind, title, slug = null, order = null, parentPath = '/',
-	invocationDirectory = siteRoot, metadata, sources = new Map(),
+	invocationDirectory = siteRoot, metadata, sources = new Map(), placement = null, targetPath = null,
 }) => {
+	const request = { siteRoot, kind, title, slug, order, parentPath, invocationDirectory, metadata, placement, targetPath };
+	if (placement !== null && !['before', 'after', 'first', 'last'].includes(placement)) throw new Error('Choose before, after, first or last.');
+	if (placement !== null && order !== null) throw new Error('Do not combine --order with a placement selector.');
 	if (kind !== 'page') throw new Error('Choose a page. Navigation categories are no longer supported; use page.listChildren: true for an overview.');
 	siteRoot = path.resolve(siteRoot);
 	title = String(title ?? '').trim();
 	if (!title || /[\r\n]/.test(title)) throw new Error('A one-line page title is required.');
 	const generatedSlug = slug === null;
 	slug ??= slugifyAsciiIdentifier(title);
-	if (!slug || !pageDirectoryPattern.test(`010-${slug}`)) {
+	if (!slug || !pageDirectoryPattern.test(slug)) {
 		throw new Error(`Invalid ${generatedSlug ? 'generated ' : ''}slug "${slug}". Use lowercase ASCII letters, numbers, and single hyphens; pass --slug when automatic transliteration is unsuitable.`);
 	}
 
 	const structure = await getSiteStructure({ siteRoot });
+	let relativeTarget = null;
+	if (placement === 'before' || placement === 'after') {
+		relativeTarget = structure.nodes.find(node => node.contentPath === targetPath || `/${node.pagePath}/` === targetPath);
+		if (!relativeTarget || relativeTarget.isHome) throw new Error('Choose an existing sibling page for before/after placement.');
+		parentPath = relativeTarget.parentPagePath ? `/${relativeTarget.parentPagePath}/` : '/';
+	}
 	const parent = await resolveParent({ nodes: structure.nodes, parent: parentPath, siteRoot, invocationDirectory });
-	const siblings = structure.nodes.filter((node) => !node.isHome && node.parentPagePath === (parent.pagePath || null));
+	const siblings = structure.nodes.filter((node) => !node.isHome && node.parentPagePath === (parent.pagePath || null)).sort(comparePageOrder);
 	if (siblings.some((node) => node.pageId === slug)) {
 		throw new Error(`Cannot create "${slug}" below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling with that slug already exists.`);
 	}
-	order = order === null ? getNextOrder(siblings) : parseOrder(String(order));
-	if (siblings.some((node) => node.pageOrder === order)) {
-		throw new Error(`Cannot use order ${String(order).padStart(3, '0')} below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling already uses it.`);
-	}
-
-	const directoryName = `${String(order).padStart(3, '0')}-${slug}`;
+	const dirty = [...sources.keys()].filter(filename => filename === path.join(siteRoot, 'site-config/settings.yaml') || siblings.some(node => node.contentPath === filename));
+	if (dirty.length) throw new Error(`Save or undo these unsaved files before choosing page placement:\n${dirty.join('\n')}`);
+	const index = placement === 'first' ? 0 : relativeTarget ? siblings.indexOf(relativeTarget) + (placement === 'after' ? 1 : 0) : siblings.length;
+	const insertion = order === null ? planPageOrder(siblings, index) : { order: parsePageOrder(Number(order), '--order'), orderChanges: [] };
+	order = insertion.order;
+	const orderChanges = await pageOrderFileChanges(insertion.orderChanges);
+	const directoryName = slug;
 	const destination = path.join(parent.collectionDir, directoryName);
 	const pagePath = [parent.pagePath, slug].filter(Boolean).join('/');
 	const state = await readEditorLinkState({ siteRoot, sources });
@@ -127,14 +121,23 @@ export const planSiteNodeCreation = async ({
 			{ pathname: `/${pagePath}/`, contentLabel: destination, aliases: metadata.page?.aliases ?? [] }],
 			categories: [], publicFiles: state.publicFiles, generatedRoutes: state.generatedRoutes }));
 	}
-	return { siteRoot, kind, title, slug, order, parentPath: parent.pagePath ? `/${parent.pagePath}/` : '/',
+	const publicationErrors = publicationIssues({ pages: [...state.graph.pages,
+		{ pathname: address, contentLabel: destination, aliases: metadata?.page?.aliases ?? [] }],
+		publicFiles: state.publicFiles, attachments: state.graph.attachments.files, generatedRoutes: state.generatedRoutes });
+	if (publicationErrors.length) throw new Error(publicationErrors.map(({ message }) => message).join('\n'));
+	metadata = { ...metadata, navigation: { ...metadata?.navigation, order } };
+	const fingerprint = JSON.stringify([destination, title, metadata, order, orderChanges, state.settings,
+		state.graph.pages.map(page => [page.contentFile.contentPath, page.document.fullSource]), state.publicFiles.map(file => file.filePath)]);
+	return { request, fingerprint, orderChanges, siteRoot, kind, title, slug, order, parentPath: parent.pagePath ? `/${parent.pagePath}/` : '/',
 		collectionDir: parent.collectionDir, destination, pagePath, url: `/${pagePath}/`, ...(metadata === undefined ? {} : { metadata }) };
 };
 
-export const createSiteNode = async (plan, { sources = new Map() } = {}) => {
+export const createSiteNode = async (plan, { sources = new Map(), allowRenumber = false, writeSource = writeFileAtomically } = {}) => {
 	// Revalidate after the author has inspected the preview. Never change its placement.
-	const current = await planSiteNodeCreation({ ...plan, sources });
-	if (current.destination !== plan.destination) throw new Error('The site changed. Preview the new location before creating the node.');
+	const current = await planSiteNodeCreation({ ...(plan.request ?? plan), sources });
+	if (current.destination !== plan.destination || current.fingerprint !== plan.fingerprint) throw new Error('The site changed. Preview the new location before creating the node.');
+	assertRenumberingAllowed(current.orderChanges, allowRenumber);
+	const written = [];
 	let createdCollection = false;
 	try {
 		const info = await stat(current.collectionDir);
@@ -156,14 +159,24 @@ export const createSiteNode = async (plan, { sources = new Map() } = {}) => {
 		const childDirectory = path.join(current.destination, 'images');
 		await mkdir(childDirectory);
 		created.push({ file: childDirectory, directory: true });
-		return { ...current, sourcePath: filename };
+		for (const change of current.orderChanges) {
+			await writeSource(change.originalPath, change.updatedSource, change.mode);
+			written.push(change);
+		}
+		return { ...current, sourcePath: filename, renumberedPages: current.orderChanges.length };
 	} catch (error) {
+		const restoreErrors = [];
+		for (const change of written.reverse()) {
+			try { await writeFileAtomically(change.originalPath, change.originalSource, change.mode); }
+			catch (failure) { restoreErrors.push(`${change.originalPath}: ${failure.message}`); }
+		}
 		// Remove only entries this operation created; never recursively remove an
 		// unexpected file written concurrently by another process.
 		for (const entry of created.reverse()) {
 			await (entry.directory ? rmdir(entry.file) : unlink(entry.file)).catch(() => {});
 		}
 		if (createdCollection) await rmdir(current.collectionDir).catch(() => {});
+		if (restoreErrors.length) throw new Error(`${error.message}\nRestoration was incomplete:\n${restoreErrors.join('\n')}`);
 		throw error;
 	}
 };

package/scripts/lib/site-paths.mjs

@@ -155,8 +155,8 @@ export const astroDistDir = configuredStateDirectory
 	: path.join(siteProjectRoot, 'dist');
 export const astroRootDir = siteStateDir;
 export const astroCacheDir = path.join(astroRootDir, '.astro');
-export const generatedImagesDir = path.join(astroPublicDir, 'images', 'generated');
-export const originalImagesDir = path.join(astroPublicDir, 'images', 'original');
+export const generatedImagesDir = path.join(astroPublicDir, '_norna', 'images', 'generated');
+export const originalImagesDir = path.join(astroPublicDir, '_norna', 'images', 'original');
 export const generatedImagesManifestPath = path.join(siteStateDir, 'generated-images.json');
 
 export const engineRootLabel = getPathLabel(engineRoot);

package/scripts/lib/site-source-format.mjs

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { load } from 'js-yaml';
+
+export const assertSiteSourceFormat = async (siteRoot, readSource = filename => readFile(filename, 'utf8')) => {
+	const filename = path.join(siteRoot, 'site-config/settings.yaml');
+	const source = await readSource(filename);
+	let settings;
+	try { settings = load(source); }
+	catch (error) { throw new Error(`${filename} contains invalid YAML: ${error.reason ?? error.message}`); }
+	if (settings?.sourceFormat !== 2) throw new Error(`${filename} needs sourceFormat: 2 after converting the site: move numeric page-directory prefixes into navigation.order frontmatter and remove those prefixes. Keep this site on its previous engine until converted. No files changed.`);
+};

package/scripts/lib/site-structure.mjs

@@ -2,6 +2,9 @@ import { getSiteSourcePaths } from './site-conventions.mjs';
 import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parsePageDirectoryPath } from './page-model.mjs';
+import { comparePageOrder, parsePageOrder } from './page-order.mjs';
+import { assertSiteSourceFormat } from './site-source-format.mjs';
+import { parseContentFrontmatter, splitSiteFile } from './site-content.mjs';
 import {
 	homePageDirectory,
 	siteDir as defaultSiteDir,
@@ -15,11 +18,6 @@ const readDirectory = async (directory) => readdir(directory, { withFileTypes: t
 	throw error;
 });
 
-const compareNodeMetadata = (left, right) => (
-	left.pageOrder - right.pageOrder
-	|| left.pageId.localeCompare(right.pageId, 'en')
-);
-
 const assertLegacyStructureIsAbsent = async ({ siteDir, siteDirLabel }) => {
 	for (const name of ['content.md', 'theme.yaml', 'images', 'pages', 'routes']) {
 		if (await fileExists(path.join(siteDir, name))) {
@@ -28,7 +26,7 @@ const assertLegacyStructureIsAbsent = async ({ siteDir, siteDirLabel }) => {
 	}
 };
 
-const assertUniqueSiblings = (nodes, pagesLabel) => {
+const assertUniqueSiblings = (nodes, pagesLabel, warnings) => {
 	const byId = new Map();
 	const byOrder = new Map();
 
@@ -43,13 +41,11 @@ const assertUniqueSiblings = (nodes, pagesLabel) => {
 		}
 		byId.set(node.pageId, node);
 
+		if (node.pageOrder === null) continue;
 		const existingOrder = byOrder.get(node.pageOrder);
 		if (existingOrder) {
-			throw new Error([
-				`${pagesLabel} contains duplicate sibling order "${String(node.pageOrder).padStart(3, '0')}".`,
-				`- ${existingOrder.nodeLabel}`,
-				`- ${node.nodeLabel}`,
-			].join('\n'));
+			const message = `${pagesLabel} contains duplicate sibling navigation.order ${node.pageOrder}: ${existingOrder.pageId} and ${node.pageId}. Slug determines their order. Choose different values to set an explicit order.`;
+			for (const sibling of [existingOrder, node]) warnings.push({ code: 'duplicate-page-order', message, label: sibling.contentLabel, path: sibling.contentPath });
 		}
 		byOrder.set(node.pageOrder, node);
 	}
@@ -75,6 +71,7 @@ export const getSiteStructure = async ({
 	};
 	try {
 		await assertLegacyStructureIsAbsent({ siteDir, siteDirLabel, sitePagesLabel });
+		await assertSiteSourceFormat(siteDir, readSource);
 	} catch (error) {
 		report(error);
 	}
@@ -131,16 +128,20 @@ export const getSiteStructure = async ({
 				imagesLabel: `${nodeLabel}/images`,
 			});
 
+			try {
+				const { frontmatterBody } = splitSiteFile(await readSource(contentPath), node.contentLabel);
+				node.pageOrder = parsePageOrder(parseContentFrontmatter(frontmatterBody, node.contentLabel).navigation?.order, `${node.contentLabel}: navigation.order`);
+			} catch (error) { report(error, node); }
 			siblingNodes.push(node);
 		}
 
 		try {
-			assertUniqueSiblings(siblingNodes, pagesLabel);
+			assertUniqueSiblings(siblingNodes, pagesLabel, warnings);
 		} catch (error) {
 			report(error);
 		}
 
-		for (const node of siblingNodes.sort(compareNodeMetadata)) {
+		for (const node of siblingNodes.sort(comparePageOrder)) {
 			nodes.push(node);
 			const childPagesDir = path.join(node.nodeDir, 'pages');
 			const childDirectories = (await readDirectory(childPagesDir)).filter((entry) => entry.isDirectory());

package/scripts/lib/site-upgrade.mjs

@@ -1,3 +1,4 @@
+import { assertSiteSourceFormat } from './site-source-format.mjs';
 import { lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { readThemePackage } from './theme-packages.mjs';
@@ -25,6 +26,7 @@ export const planSiteUpgrade = async (siteRoot) => {
 	for (const filename of [source.content, path.join(siteRoot, 'site-config', 'settings.yaml'), source.theme]) {
 		if (!(await inspect(filename))?.isFile()) throw new Error(`${filename} is required and must be a regular file.`);
 	}
+	await assertSiteSourceFormat(siteRoot);
 	await readThemePackage({ siteRoot, filename: source.theme });
 	return { siteRoot, moves: [] };
 };

package/scripts/lib/social-image-assets.mjs

@@ -1,3 +1,4 @@
+import { publicFilePublication } from './publication-paths.mjs';
 import { getPublicAssetInspection } from './logo-assets.mjs';
 import {
 	socialImageAssetDefinitions,
@@ -13,7 +14,7 @@ export const getSocialImageAssets = () => getPublicAssetInspection().socialImage
 	.map((filename) => ({
 		...definitionsByFilename.get(filename),
 		filename,
-		href: `/${filename}`,
+		href: publicFilePublication(filename).pathname,
 	}));
 
 export const getSocialImageAsset = () => {

package/scripts/lib/source-files.mjs

@@ -11,7 +11,7 @@ export const sourceFileDefinitions = [
 	{ name: 'tree-theme.yaml', location: 'page', schemaKind: 'theme', rootSchemaKind: 'rootTheme', required: 'root', rootText: 'preset: documentation\n', text: '# Modify inherited settings. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page and its descendants. Without preset, modifies inherited values; preset selects a new base. Required on the root page.', removalEffect: 'This branch resumes the ancestor tree theme. Overrides on descendants remain; a descendant preset starts an independent base.' },
 	{ name: 'page-theme.yaml', location: 'page', schemaKind: 'pageTheme', text: '# Modify this page only. Add preset only to replace the complete base.\n{}\n', description: 'Visual settings for this page only. Without preset, modifies its tree theme; preset selects a new base. Descendants keep their tree theme.', removalEffect: 'This page will use its selected tree theme again. Other pages are unchanged.' },
 ];
-export const sourcePageDirectoryPattern = pageDirectoryPattern.source.replace('^', '^(?!000-)');
+export const sourcePageDirectoryPattern = pageDirectoryPattern.source;
 const schemas = { config: configSchema, contentFrontmatter: siteSchema, sitewideContent: sitewideSchema, theme: themeVisualSchema, rootTheme: rootThemeSchema, pageTheme: pageThemeSchema };
 
 export const getSourcePageLocation = (siteRoot, directory) => {

package/scripts/lib/structured-blocks.mjs

@@ -1,5 +1,7 @@
 import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from 'yaml';
 
+export const managedImageFilenamePattern = '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])';
+
 const stringSchema = (name, definition) => ({
 	type: 'string',
 	description: definition.description,
@@ -7,7 +9,7 @@ const stringSchema = (name, definition) => ({
 	...(definition.values ? { enum: Object.keys(definition.values) } : {}),
 	...(name === 'alt' ? {} : { minLength: 1 }),
 	pattern: name === 'image'
-		? '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])'
+		? managedImageFilenamePattern
 		: name === 'caption' || name === 'text'
 			? '^(?=[\\s\\S]*\\S)[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F-\\x9F]*$(?![\\s\\S])'
 			: name === 'alt'