@janga/norna 0.7.26 → 0.7.28

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

@@ -151,7 +151,7 @@ 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.',
+		'`site-config/settings.yaml` contains the few technical settings shared by the complete site.',
 		documentationLink('Configuration reference', 'configuration.md'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'url', [
@@ -283,7 +283,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 +463,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 +544,10 @@ const addContentHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'page.description', [
 		yamlExample('page:\n  description: About this project.'),
-		'An optional page-specific description rendered as `<meta name="description">`. It is not visible in page content.',
+		'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.',
@@ -604,28 +566,19 @@ const addContentHelp = (jsonSchema) => {
 	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',
@@ -154,28 +152,19 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 		} else if (fileKind === 'content' && key === 'images') {
 			fix = 'Put local image references in image-stack or image-carousel blocks in the Markdown body.';
 		} 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('/')
+);

package/scripts/lib/site-navigation-tree.mjs

@@ -30,7 +30,6 @@ export const getListedSiteNavigationTree = (entries) => {
 	const filterListed = (nodes) => nodes.flatMap((node) => {
 		if (!node.node.isHome && !node.node.navigation.listed) return [];
 		const children = filterListed(node.children);
-		if (node.node.kind === 'category' && children.length === 0) return [];
 		return [{ ...node, children }];
 	});
 
@@ -48,9 +47,7 @@ export const getSequentialPageNavigation = (nodes, currentPagePath) => {
 	));
 	if (!activeRoot) return { previous: null, next: null };
 
-	const pages = flattenSiteNavigationTree([activeRoot])
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ node }) => node);
+	const pages = flattenSiteNavigationTree([activeRoot]).map(({ node }) => node);
 	const currentIndex = pages.findIndex(({ pagePath }) => pagePath === currentPagePath);
 	if (currentIndex < 0) return { previous: null, next: null };
 
@@ -68,7 +65,5 @@ export const getDirectChildPages = (nodes, currentPagePath) => {
 		? nodes.filter(({ node }) => !node.isHome)
 		: current.children;
 
-	return children
-		.filter(({ node }) => node.kind === 'page')
-		.map(({ node }) => node);
+	return children.map(({ node }) => node);
 };

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

@@ -0,0 +1,169 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import { mkdir, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { dump as dumpYaml } from 'js-yaml';
+import { slugifyAsciiIdentifier } from './heading-ids.mjs';
+import { pageDirectoryPattern } from './page-model.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+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;
+};
+
+const normalizeParentPath = (value) => {
+	if (value === '/') return '';
+	if (value.includes('\\') || value.includes('?') || value.includes('#')) {
+		throw new Error(`Invalid --parent "${value}". Use a logical path such as /guides/installation/.`);
+	}
+	const normalized = value.replace(/^\/+|\/+$/g, '');
+	if (!normalized || normalized.split('/').some((segment) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment))) {
+		throw new Error(`Invalid --parent "${value}". Use / for the top level or a logical path such as /guides/installation/.`);
+	}
+	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) => {
+	if (error?.code === 'ENOENT') return path.resolve(directory);
+	throw error;
+});
+
+const resolveParent = async ({ nodes, parent, siteRoot, invocationDirectory }) => {
+	const sitePagesDir = getSiteSourcePaths(siteRoot).pages;
+	if (parent !== null) {
+		const parentPath = normalizeParentPath(parent);
+		if (!parentPath) {
+			return { collectionDir: sitePagesDir, node: null, pagePath: '' };
+		}
+		const node = nodes.find((candidate) => candidate.pagePath === parentPath);
+		if (!node) {
+			throw new Error(`Cannot find parent "${parent}". Use an existing page path, or / for the top level.`);
+		}
+		return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+	}
+
+	const currentDirectory = await canonicalDirectory(invocationDirectory);
+	if (currentDirectory === await canonicalDirectory(sitePagesDir) || currentDirectory === await canonicalDirectory(siteRoot)) {
+		return { collectionDir: sitePagesDir, node: null, pagePath: '' };
+	}
+	let node = null;
+	for (const candidate of nodes) {
+		if (await canonicalDirectory(candidate.nodeDir) === currentDirectory) {
+			node = candidate;
+			break;
+		}
+	}
+	if (!node) {
+		throw new Error([
+			'Cannot infer where to add the node from the current directory.',
+			`Run the command from ${sitePagesDir} for a top-level node, from an existing page directory for a child, or pass --parent.`,
+		].join('\n'));
+	}
+	return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
+};
+
+// 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(),
+}) => {
+	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}`)) {
+		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 });
+	const parent = await resolveParent({ nodes: structure.nodes, parent: parentPath, siteRoot, invocationDirectory });
+	const siblings = structure.nodes.filter((node) => !node.isHome && node.parentPagePath === (parent.pagePath || null));
+	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 destination = path.join(parent.collectionDir, directoryName);
+	const pagePath = [parent.pagePath, slug].filter(Boolean).join('/');
+	const state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Page addresses could not be checked. ${state.incomplete.join('\n')}`);
+	const address = `/${pagePath}/`;
+	const owner = state.graph.aliasModel.identitiesByPathname.get(address);
+	if (owner?.kind === 'page-alias') {
+		const page = owner.source.page;
+		throw new Error(`${address} is a previous address for “${page.title}”, now at ${owner.source.targetPathname}. Choose another URL segment, or remove this previous address from “${page.title}” through Addresses and links… → Additional addresses….`);
+	}
+	if (owner) throw new Error(`Address ${address} is already in use by ${owner.label}. Choose another URL segment.`);
+	if (metadata !== undefined) {
+		metadata = parseYamlConfig(dumpYaml(metadata), 'Page information', { schema: siteSchema });
+		assertPageAliasModel(createPageAliasModel({ pages: [...state.graph.pages,
+			{ 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}/` : '/',
+		collectionDir: parent.collectionDir, destination, pagePath, url: `/${pagePath}/`, ...(metadata === undefined ? {} : { metadata }) };
+};
+
+export const createSiteNode = async (plan, { sources = new Map() } = {}) => {
+	// 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.');
+	let createdCollection = false;
+	try {
+		const info = await stat(current.collectionDir);
+		if (!info.isDirectory()) throw new Error(`${current.collectionDir} exists but is not a directory.`);
+	} catch (error) {
+		if (error.code !== 'ENOENT') throw error;
+		await mkdir(current.collectionDir);
+		createdCollection = true;
+	}
+	const created = [];
+	try {
+		// Exclusive reservation also protects an empty destination created after planning.
+		await mkdir(current.destination);
+		created.push({ file: current.destination, directory: true });
+		const filename = path.join(current.destination, 'content.md');
+		const source = `${current.metadata && Object.keys(current.metadata).length ? `---\n${dumpYaml(current.metadata, { lineWidth: -1, noRefs: true })}---\n\n` : ''}# ${escapeMarkdownHeading(current.title)}\n\n## Introduction\n\nStart writing here.\n`;
+		await writeFile(filename, source, { flag: 'wx' });
+		created.push({ file: filename });
+		const childDirectory = path.join(current.destination, 'images');
+		await mkdir(childDirectory);
+		created.push({ file: childDirectory, directory: true });
+		return { ...current, sourcePath: filename };
+	} catch (error) {
+		// 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(() => {});
+		throw error;
+	}
+};

package/scripts/lib/site-paths.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homePageDirectory } from './site-conventions.mjs';
+import { getSiteSourcePaths, homePageDirectory, legacyHomePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
@@ -32,9 +32,10 @@ if (hasStateDirectoryEnv && !configuredStateDirectory) {
 
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
-		existsSync(path.join(siteDir, 'config.yaml'))
+		(existsSync(path.join(siteDir, 'site-config', 'settings.yaml')) || existsSync(path.join(siteDir, 'config.yaml')))
 		&& (
-			existsSync(path.join(siteDir, 'pages', homePageDirectory, 'content.md'))
+			existsSync(path.join(siteDir, 'pages', legacyHomePageDirectory, 'content.md'))
+			|| existsSync(getSiteSourcePaths(siteDir).content)
 			|| existsSync(path.join(siteDir, 'content.md'))
 		)
 	);
@@ -63,6 +64,16 @@ const findSiteProjectRoot = (startDirectory, siteDirectory) => {
 	}
 };
 
+const findContainingSite = (startDirectory) => {
+	let current = path.resolve(startDirectory);
+	while (true) {
+		if (hasSiteFilesInDirectory(current)) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+};
+
 const hasSiteDirectoryEnv = Object.hasOwn(process.env, siteDirectoryEnvName);
 const configuredSiteDirectory = normalizeSiteDirectory(process.env[siteDirectoryEnvName]);
 const hasConfiguredSiteDirectory = hasSiteDirectoryEnv && configuredSiteDirectory !== '';
@@ -84,8 +95,9 @@ const resolveSitePaths = () => {
 		};
 	}
 
-	if (!hasConfiguredSiteDirectory && hasSiteFilesInDirectory(invocationRoot)) {
-		const siteDir = invocationRoot;
+	const containingSite = !hasConfiguredSiteDirectory && findContainingSite(invocationRoot);
+	if (containingSite) {
+		const siteDir = containingSite;
 		const siteProjectRoot = path.dirname(siteDir);
 
 		return {
@@ -126,11 +138,11 @@ const getPathLabel = (filePath) => {
 };
 
 export const siteDir = resolvedSitePaths.siteDir;
-export const siteConfigPath = path.join(siteDir, 'config.yaml');
-export const siteThemePath = path.join(siteDir, 'theme.yaml');
-export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
-export const sitePagesDir = path.join(siteDir, 'pages');
-export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
+export const siteConfigPath = path.join(siteDir, 'site-config', 'settings.yaml');
+export const siteThemePath = getSiteSourcePaths(siteDir).theme;
+export const sitewideContentPath = path.join(siteDir, 'site-config', 'shared-content.yaml');
+export const sitePagesDir = getSiteSourcePaths(siteDir).pages;
+export const siteHomePageDir = getSiteSourcePaths(siteDir).root;
 export const siteContentPath = path.join(siteHomePageDir, 'content.md');
 export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');