@janga/norna 0.7.26 → 0.7.28

package/scripts/lib/documentation-routes.json

@@ -0,0 +1,229 @@
+{
+  "sources": {
+    "": "site/root/pages/032-reference/content.md",
+    "site/": "site/root/pages/032-reference/pages/010-site/content.md",
+    "site/files/": "site/root/pages/032-reference/pages/010-site/pages/010-files/content.md",
+    "site/pages/": "site/root/pages/032-reference/pages/010-site/pages/020-pages/content.md",
+    "site/urls/": "site/root/pages/032-reference/pages/010-site/pages/030-urls/content.md",
+    "site/metadata/": "site/root/pages/032-reference/pages/010-site/pages/040-metadata/content.md",
+    "site/images/": "site/root/pages/032-reference/pages/010-site/pages/050-images/content.md",
+    "site/public-files/": "site/root/pages/032-reference/pages/010-site/pages/060-public-files/content.md",
+    "site/requirements/": "site/root/pages/032-reference/pages/010-site/pages/070-requirements/content.md",
+    "configuration/": "site/root/pages/032-reference/pages/020-configuration/content.md",
+    "configuration/site/": "site/root/pages/032-reference/pages/020-configuration/pages/010-site/content.md",
+    "configuration/language/": "site/root/pages/032-reference/pages/020-configuration/pages/020-language/content.md",
+    "configuration/navigation/": "site/root/pages/032-reference/pages/020-configuration/pages/030-navigation/content.md",
+    "configuration/search/": "site/root/pages/032-reference/pages/020-configuration/pages/040-search/content.md",
+    "configuration/source-links/": "site/root/pages/032-reference/pages/020-configuration/pages/050-source-links/content.md",
+    "configuration/theme/": "site/root/pages/032-reference/pages/020-configuration/pages/060-theme/content.md",
+    "configuration/presets/": "site/root/pages/032-reference/pages/020-configuration/pages/065-presets/content.md",
+    "configuration/palettes/": "site/root/pages/032-reference/pages/020-configuration/pages/070-palettes/content.md",
+    "configuration/appearance/": "site/root/pages/032-reference/pages/020-configuration/pages/080-appearance/content.md",
+    "configuration/layout/": "site/root/pages/032-reference/pages/020-configuration/pages/090-layout/content.md",
+    "configuration/images/": "site/root/pages/032-reference/pages/020-configuration/pages/100-images/content.md",
+    "configuration/typography/": "site/root/pages/032-reference/pages/020-configuration/pages/110-typography/content.md",
+    "configuration/sections/": "site/root/pages/032-reference/pages/020-configuration/pages/120-sections/content.md",
+    "configuration/shared-content/": "site/root/pages/032-reference/pages/020-configuration/pages/130-shared-content/content.md",
+    "content/": "site/root/pages/032-reference/pages/030-content/content.md",
+    "content/markdown/": "site/root/pages/032-reference/pages/030-content/pages/010-markdown/content.md",
+    "content/structured-blocks/": "site/root/pages/032-reference/pages/030-content/pages/015-structured-blocks/content.md",
+    "content/images/": "site/root/pages/032-reference/pages/030-content/pages/020-images/content.md",
+    "content/cards/": "site/root/pages/032-reference/pages/030-content/pages/030-cards/content.md",
+    "content/child-lists/": "site/root/pages/032-reference/pages/030-content/pages/040-child-lists/content.md",
+    "content/callouts/": "site/root/pages/032-reference/pages/030-content/pages/050-callouts/content.md",
+    "content/tabs/": "site/root/pages/032-reference/pages/030-content/pages/060-tabs/content.md",
+    "content/details/": "site/root/pages/032-reference/pages/030-content/pages/070-details/content.md",
+    "content/tables/": "site/root/pages/032-reference/pages/030-content/pages/080-tables/content.md",
+    "content/code/": "site/root/pages/032-reference/pages/030-content/pages/090-code/content.md",
+    "content/sidenotes/": "site/root/pages/032-reference/pages/030-content/pages/100-sidenotes/content.md",
+    "content/footnotes/": "site/root/pages/032-reference/pages/030-content/pages/110-footnotes/content.md",
+    "commands/": "site/root/pages/032-reference/pages/040-commands/content.md",
+    "commands/invocation/": "site/root/pages/032-reference/pages/040-commands/pages/010-invocation/content.md",
+    "commands/init/": "site/root/pages/032-reference/pages/040-commands/pages/020-init/content.md",
+    "commands/create/": "site/root/pages/032-reference/pages/040-commands/pages/030-create/content.md",
+    "commands/move/": "site/root/pages/032-reference/pages/040-commands/pages/040-move/content.md",
+    "commands/validate/": "site/root/pages/032-reference/pages/040-commands/pages/050-validate/content.md",
+    "commands/navigation/": "site/root/pages/032-reference/pages/040-commands/pages/055-navigation/content.md",
+    "commands/development/": "site/root/pages/032-reference/pages/040-commands/pages/060-development/content.md",
+    "commands/build/": "site/root/pages/032-reference/pages/040-commands/pages/070-build/content.md",
+    "commands/publishing/": "site/root/pages/032-reference/pages/040-commands/pages/080-publishing/content.md",
+    "commands/theme/": "site/root/pages/032-reference/pages/040-commands/pages/090-theme/content.md",
+    "commands/engine/": "site/root/pages/032-reference/pages/040-commands/pages/100-engine/content.md",
+    "commands/migration-audit/": "site/root/pages/032-reference/pages/040-commands/pages/110-migration-audit/content.md",
+    "reader/": "site/root/pages/032-reference/pages/050-reader/content.md",
+    "reader/display/": "site/root/pages/032-reference/pages/050-reader/pages/010-display/content.md",
+    "reader/accessibility/": "site/root/pages/032-reference/pages/050-reader/pages/020-accessibility/content.md",
+    "workflows/": "site/root/pages/032-reference/pages/060-workflows/content.md",
+    "workflows/editor/": "site/root/pages/032-reference/pages/060-workflows/pages/010-editor/content.md",
+    "workflows/editor-ai-suggestions/": "site/root/pages/032-reference/pages/060-workflows/pages/015-editor-ai-suggestions/content.md",
+    "workflows/publishing/": "site/root/pages/032-reference/pages/060-workflows/pages/020-publishing/content.md",
+    "workflows/embedded-publishing/": "site/root/pages/032-reference/pages/060-workflows/pages/030-embedded-publishing/content.md",
+    "workflows/upgrading/": "site/root/pages/032-reference/pages/060-workflows/pages/040-upgrading/content.md",
+    "workflows/legacy-source/": "site/root/pages/032-reference/pages/060-workflows/pages/050-legacy-source/content.md"
+  },
+  "legacy": {
+    "site-files.md": "site/files/",
+    "pages.md": "site/pages/",
+    "configuration.md": "configuration/site/",
+    "content.md": "content/markdown/",
+    "theme.md": "configuration/theme/",
+    "typography.md": "configuration/typography/",
+    "images-and-metadata.md": "site/images/",
+    "public-files.md": "site/public-files/",
+    "sitewide-content.md": "configuration/shared-content/",
+    "commands.md": "commands/invocation/",
+    "local-development.md": "commands/development/",
+    "requirements.md": "site/requirements/",
+    "publishing.md": "workflows/publishing/",
+    "upgrading.md": "workflows/upgrading/",
+    "editor-support.md": "workflows/editor/",
+    "client-javascript.md": "reader/accessibility/",
+    "presentation-guarantees.md": "reader/accessibility/",
+    "site-files.md#root-files": "site/files/#source-layout",
+    "site-files.md#page-hierarchy": "site/files/#page-folders",
+    "site-files.md#public-files": "site/public-files/",
+    "site-files.md#selecting-the-site-directory": "commands/invocation/#site-selection",
+    "site-files.md#versioned-files": "site/files/#generated-files",
+    "site-files.md#generated-files": "site/files/#generated-files",
+    "pages.md#homepage-and-top-level-entries": "site/pages/#choose-pages-and-sections",
+    "pages.md#choose-a-section-page-or-category": "site/pages/#choose-pages-and-sections",
+    "pages.md#review-an-existing-hierarchy": "commands/navigation/",
+    "pages.md#navigation-categories": "site/pages/#choose-pages-and-sections",
+    "pages.md#opening-a-category-url": "site/pages/#list-child-pages",
+    "pages.md#reachable-content-and-stable-links": "site/pages/#list-child-pages",
+    "pages.md#nested-pages": "site/pages/#choose-pages-and-sections",
+    "pages.md#directory-names-order-and-urls": "site/pages/#names-and-order",
+    "pages.md#preserve-old-page-urls": "site/urls/#keep-an-old-url",
+    "pages.md#move-or-reconcile-a-page": "commands/move/",
+    "pages.md#create-pages-and-categories": "commands/create/",
+    "pages.md#page-content": "content/markdown/",
+    "pages.md#navigation": "configuration/navigation/",
+    "pages.md#focus-reading": "reader/display/#focus-reading",
+    "pages.md#current-reading-position": "configuration/navigation/#orientation-and-long-trees",
+    "pages.md#page-images": "site/images/",
+    "pages.md#page-themes": "configuration/theme/#page-themes",
+    "configuration.md#url": "configuration/site/#public-url",
+    "configuration.md#language": "configuration/language/",
+    "configuration.md#what-the-setting-changes": "configuration/language/",
+    "configuration.md#choose-a-language-tag": "configuration/language/",
+    "configuration.md#supported-languages": "configuration/language/",
+    "configuration.md#search-and-translation-boundaries": "configuration/language/",
+    "configuration.md#edit-link": "configuration/source-links/",
+    "configuration.md#local-editor": "configuration/source-links/#destination-rules",
+    "configuration.md#remote-source-host": "configuration/source-links/#fields",
+    "configuration.md#navigation": "configuration/navigation/",
+    "configuration.md#navigationmode": "configuration/navigation/",
+    "configuration.md#one-page-sections": "configuration/navigation/",
+    "configuration.md#top-level-pages-top": "configuration/navigation/",
+    "configuration.md#child-pages-or-categories-tree": "configuration/navigation/",
+    "configuration.md#search": "configuration/search/",
+    "configuration.md#scrollbehavior": "configuration/site/#anchor-movement",
+    "configuration.md#publishing-discovery": "commands/publishing/",
+    "configuration.md#site-directory-selection": "commands/invocation/#site-selection",
+    "content.md#page-title-and-frontmatter": "site/metadata/",
+    "content.md#sections": "content/markdown/#page-title-and-sections",
+    "content.md#internal-links": "site/urls/",
+    "content.md#norna-blocks": "content/structured-blocks/",
+    "content.md#child-page-list": "content/child-lists/",
+    "content.md#image-stack": "content/images/#image-stack",
+    "content.md#image-carousel": "content/images/#image-carousel",
+    "content.md#card-list": "content/cards/",
+    "content.md#image-files": "site/images/",
+    "content.md#markdown-images": "content/markdown/#markdown-images",
+    "content.md#markdown-text": "content/markdown/#standard-syntax-and-extensions",
+    "content.md#semantic-callouts": "content/callouts/",
+    "content.md#tabs": "content/tabs/",
+    "content.md#details-disclosures": "content/details/",
+    "content.md#tables": "content/tables/",
+    "content.md#row-headings": "content/tables/#row-headings",
+    "content.md#sorting": "content/tables/#sorting",
+    "content.md#width-and-scrolling": "content/tables/#width-and-sticky-context",
+    "content.md#code-blocks": "content/code/",
+    "content.md#side-notes": "content/sidenotes/",
+    "content.md#reference-footnotes": "content/footnotes/",
+    "content.md#validation-and-sync": "commands/validate/",
+    "images-and-metadata.md#managed-source-images": "site/images/#source-files",
+    "images-and-metadata.md#managed-image-presentation": "configuration/images/",
+    "images-and-metadata.md#captions-for-tall-images": "configuration/images/#tall-captions-and-inspection",
+    "images-and-metadata.md#inspecting-detailed-images": "configuration/images/#tall-captions-and-inspection",
+    "images-and-metadata.md#markdown-images": "content/markdown/#markdown-images",
+    "images-and-metadata.md#generated-variants-and-static-svg": "site/images/#variants-and-svg",
+    "images-and-metadata.md#manifest": "site/images/#manifest-and-cache",
+    "images-and-metadata.md#metadata-behavior": "site/images/#credits-and-provenance",
+    "images-and-metadata.md#ai-generated-images": "site/images/#credits-and-provenance",
+    "images-and-metadata.md#github-actions-cache": "site/images/#manifest-and-cache",
+    "public-files.md#navigation-logo": "site/public-files/#recognized-files",
+    "public-files.md#browser-icons": "site/public-files/#recognized-files",
+    "public-files.md#social-sharing-image": "site/public-files/#social-previews",
+    "public-files.md#github-pages-custom-domain": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#generated-sitemap": "site/public-files/#generated-sitemap",
+    "public-files.md#generated-404-page": "site/public-files/#generated-404-page",
+    "public-files.md#other-static-files": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#generated-copy": "site/public-files/#preparation-and-reserved-paths",
+    "theme.md#theme-presets": "configuration/presets/",
+    "theme.md#choose-a-preset": "configuration/theme/#presets-and-root-overrides",
+    "theme.md#portfolio": "configuration/presets/#portfolio",
+    "theme.md#documentation": "configuration/presets/#documentation",
+    "theme.md#project": "configuration/presets/#project",
+    "theme.md#statement": "configuration/presets/#statement",
+    "theme.md#overrides": "configuration/theme/#presets-and-root-overrides",
+    "theme.md#export-a-preset": "commands/theme/#list-and-export-presets",
+    "theme.md#layout": "configuration/layout/",
+    "theme.md#image-sizing": "configuration/images/",
+    "theme.md#content-block-defaults": "content/cards/#width",
+    "theme.md#typography": "configuration/typography/",
+    "theme.md#palette-and-appearance": "configuration/palettes/",
+    "theme.md#palette": "configuration/palettes/",
+    "theme.md#appearance": "configuration/appearance/",
+    "theme.md#reader-display-controls": "reader/display/",
+    "theme.md#corners": "configuration/theme/#visual-settings",
+    "theme.md#section-backgrounds": "configuration/sections/",
+    "theme.md#page-themes": "configuration/theme/#page-themes",
+    "typography.md#typography-profiles": "configuration/typography/#font-profile-and-rhythm",
+    "typography.md#typography-rhythm": "configuration/typography/#font-profile-and-rhythm",
+    "typography.md#configuration-shape": "configuration/typography/#override-fields",
+    "typography.md#override-values": "configuration/typography/#override-fields",
+    "typography.md#page-text-width": "configuration/layout/",
+    "sitewide-content.md#logo": "configuration/shared-content/#logo",
+    "sitewide-content.md#banners": "configuration/shared-content/#banners",
+    "sitewide-content.md#footer": "configuration/shared-content/#footer",
+    "commands.md#cli-commands": "commands/invocation/#command-map",
+    "commands.md#starter-npm-scripts": "commands/invocation/#project-npm-scripts",
+    "commands.md#create-pages-and-categories": "commands/create/",
+    "commands.md#move-a-page": "commands/move/",
+    "commands.md#review-navigation-structure": "commands/navigation/",
+    "commands.md#command-summary": "commands/invocation/#command-map",
+    "local-development.md#start-local-preview": "commands/development/",
+    "local-development.md#test-on-a-phone": "commands/development/#lan-preview",
+    "local-development.md#manage-preview": "commands/development/#lifecycle-commands",
+    "local-development.md#when-startup-fails": "commands/development/#preparation-failures-and-stale-output",
+    "local-development.md#rebuild-stale-preview": "commands/development/#preparation-failures-and-stale-output",
+    "publishing.md#requirements": "workflows/publishing/",
+    "publishing.md#github-pages-workflow": "workflows/publishing/#configure-and-publish",
+    "publishing.md#publish-an-embedded-site-beside-another-static-build": "workflows/embedded-publishing/",
+    "publishing.md#deploy-an-already-committed-branch": "commands/publishing/#deploy-committed-sources",
+    "publishing.md#deploy-with-a-generated-commit": "commands/publishing/#build-and-create-a-commit",
+    "publishing.md#watch-a-deploy": "commands/publishing/#monitor-a-workflow",
+    "upgrading.md#before-changing-the-site": "workflows/upgrading/#establish-the-baseline",
+    "upgrading.md#safest-pre-10-migration": "workflows/upgrading/#older-source-models",
+    "upgrading.md#current-source-layout": "workflows/legacy-source/",
+    "upgrading.md#routine-engine-updates": "workflows/upgrading/#update-and-review",
+    "upgrading.md#validate-the-migration": "workflows/upgrading/#update-and-review",
+    "editor-support.md#install-the-extension": "workflows/editor/#install-and-verify",
+    "editor-support.md#what-you-see-in-vs-code": "workflows/editor/#install-and-verify",
+    "editor-support.md#requirements": "workflows/editor/#install-and-verify",
+    "editor-support.md#recognized-files": "workflows/editor/#recognized-files",
+    "editor-support.md#configuration-help": "workflows/editor/#suggestions-and-diagnostics",
+    "editor-support.md#markdown-and-image-help": "workflows/editor/#managed-images-and-quick-fixes",
+    "editor-support.md#refresh-after-an-engine-change": "workflows/editor/#refresh-and-troubleshoot",
+    "editor-support.md#troubleshooting": "workflows/editor/#refresh-and-troubleshoot",
+    "editor-support.md#turn-off-ai-suggestions-while-keeping-intellisense": "workflows/editor-ai-suggestions/",
+    "client-javascript.md#feature-contract": "reader/accessibility/#without-javascript",
+    "client-javascript.md#choosing-static-alternatives": "reader/accessibility/#without-javascript",
+    "presentation-guarantees.md#color-and-focus": "reader/accessibility/#color-focus-and-controls",
+    "presentation-guarantees.md#typography-and-reading-width": "reader/accessibility/#reading-and-reflow",
+    "presentation-guarantees.md#reflow-and-text-adaptation": "reader/accessibility/#reading-and-reflow",
+    "presentation-guarantees.md#controls-and-user-preferences": "reader/display/",
+    "presentation-guarantees.md#author-responsibilities": "reader/accessibility/#author-responsibilities"
+  }
+}

package/scripts/lib/docusaurus-migration-audit.mjs

@@ -1,3 +1,4 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
@@ -584,14 +585,16 @@ export const writeMigrationReport = async (report, reportDir, { sourceRoot = nul
 		const entries = await readdir(resolvedReportDir);
 		if (entries.length > 0) throw new Error('Migration report directory must be empty: ' + resolvedReportDir);
 	} else await mkdir(resolvedReportDir, { recursive: true });
-	await mkdir(path.join(resolvedReportDir, 'pages', '000-home'), { recursive: true });
-	await writeFile(path.join(resolvedReportDir, 'config.yaml'), 'url: https://example.invalid/\n');
-	await writeFile(path.join(resolvedReportDir, 'theme.yaml'), 'preset: documentation\n');
-	await writeFile(path.join(resolvedReportDir, 'pages', '000-home', 'content.md'), renderReportHome(report));
+	const source = getSiteSourcePaths(resolvedReportDir);
+	await mkdir(source.pages, { recursive: true });
+	await mkdir(path.join(resolvedReportDir, 'site-config'), { recursive: true });
+	await writeFile(path.join(resolvedReportDir, 'site-config/settings.yaml'), 'url: https://example.invalid/\n');
+	await writeFile(path.join(resolvedReportDir, 'root', 'tree-theme.yaml'), 'preset: documentation\n');
+	await writeFile(source.content, renderReportHome(report));
 	if (report.problemTypes.length > 0) {
-		const categoryDir = path.join(resolvedReportDir, 'pages', '010-problems');
+		const categoryDir = path.join(source.pages, '010-problems');
 		await mkdir(path.join(categoryDir, 'pages'), { recursive: true });
-		await writeFile(path.join(categoryDir, 'category.yaml'), 'label: Problems\n');
+		await writeFile(path.join(categoryDir, 'content.md'), '---\npage:\n  listChildren: true\n---\n\n# Problems\n');
 		for (const [index, problem] of report.problemTypes.entries()) {
 			const pageDir = path.join(categoryDir, 'pages', String((index + 1) * 10).padStart(3, '0') + '-' + problemPageId(problem));
 			await mkdir(pageDir, { recursive: true });

package/scripts/lib/editor-file-policy.mjs

@@ -0,0 +1,18 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import path from 'node:path';
+import { getSourceFileDefinition } from './source-files.mjs';
+import { isInside } from './editor-site-links.mjs';
+
+export const editorFileRemovalPolicy = ({ siteRoot, sourcePath, filePath }) => {
+	const directory = path.dirname(sourcePath);
+	const siteOwner = sourcePath === siteRoot || directory === getSiteSourcePaths(siteRoot).root;
+	const definition = getSourceFileDefinition(siteRoot, filePath);
+	if (definition && !definition.required && definition.removalEffect
+		&& (path.dirname(filePath) === directory || definition.location === 'site-config' && siteOwner)) {
+		return { kind: definition.schemaKind === 'sitewideContent' ? 'shared-content' : 'theme', effect: definition.removalEffect };
+	}
+	if (siteOwner && isInside(path.join(siteRoot, 'public'), filePath)) return {
+		kind: 'public', effect: 'This file will no longer be published. Links to it may break; an icon or logo may disappear. References outside page content are not checked.',
+	};
+	return null;
+};

package/scripts/lib/editor-language-service.mjs

@@ -17,11 +17,14 @@ import {
 	socialImageAssetFilenames,
 } from './public-asset-conventions.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
+import { selectPageTheme } from './theme-packages.mjs';
+import { getSourcePageLocation } from './source-files.mjs';
+import { assertSectionBackgroundPatternCompatibility } from './presentation.mjs';
 import { siteSchema } from './schema-definitions.mjs';
-import { homePageDirectory } from './site-conventions.mjs';
+import { getSiteSourcePaths, homePageDirectory } from './site-conventions.mjs';
 
 const supportedImageExtensions = new Set(['.jpg', '.jpeg', '.png', '.svg']);
-const siteConfigNames = ['config.yaml'];
+const siteConfigNames = ['site-config/settings.yaml'];
 const fileExists = (filePath) => access(filePath).then(() => true, () => false);
 const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 
@@ -79,45 +82,35 @@ const getNavigationNodesForEditor = async (siteRoot) => {
 		for (const entry of entries) {
 			const nodeDirectory = path.join(pagesDirectory, entry.name);
 			const contentPath = path.join(nodeDirectory, 'content.md');
-			const categoryPath = path.join(nodeDirectory, 'category.yaml');
-			const [hasContent, hasCategory] = await Promise.all([
-				fileExists(contentPath),
-				fileExists(categoryPath),
-			]);
-
-			if (hasContent !== hasCategory) {
-				if (hasCategory) {
-					nodes.push({
-						depth,
-						headings: [],
-						isHome: false,
-						kind: 'category',
-						listed: true,
-					});
-				} else {
-					const source = await readFile(contentPath, 'utf8');
-					const data = readContentFrontmatterForEditor(source);
-					const document = await parsePageMarkdownSource(source, { label: contentPath });
-					nodes.push({
-						depth,
-						headings: document.navigationHeadings,
-						isHome: depth === 1 && entry.name === homePageDirectory,
-						kind: 'page',
-						listed: data.navigation?.listed !== false,
-					});
-				}
+			if (await fileExists(contentPath)) {
+				const source = await readFile(contentPath, 'utf8');
+				const data = readContentFrontmatterForEditor(source);
+				const document = await parsePageMarkdownSource(source, { label: contentPath });
+				nodes.push({
+					depth,
+					headings: document.navigationHeadings,
+					isHome: false,
+					kind: 'page',
+					listed: data.navigation?.listed !== false,
+				});
 			}
 
 			await visit(path.join(nodeDirectory, 'pages'), depth + 1);
 		}
 	};
 
-	await visit(path.join(siteRoot, 'pages'));
+	const homeContent = getSiteSourcePaths(siteRoot).content;
+	if (await fileExists(homeContent)) {
+		const source = await readFile(homeContent, 'utf8');
+		const document = await parsePageMarkdownSource(source, { label: homeContent });
+		nodes.unshift({ depth: 0, headings: document.navigationHeadings, isHome: true, kind: 'page', listed: true });
+	}
+	await visit(getSiteSourcePaths(siteRoot).pages);
 	return nodes;
 };
 
 const getNavigationModeForEditor = async (siteRoot) => {
-	const config = await readEditorYaml(path.join(siteRoot, 'config.yaml'));
+	const config = await readEditorYaml(path.join(siteRoot, 'site-config', 'settings.yaml'));
 	if (!config) return null;
 	const requestedMode = config.navigation?.mode ?? 'automatic';
 	if (requestedMode !== 'automatic') return requestedMode;
@@ -148,30 +141,33 @@ const findNestedYamlPropertyLine = (source, parentKey, propertyKey) => {
 	return 1;
 };
 
-export const getThemeDiagnostics = async ({ documentPath, source }) => {
-	let theme;
+export const getThemeDiagnostics = async ({ siteRoot, documentPath, source, sources = new Map() }) => {
+	// Parse errors are reported by the YAML provider/schema validator.
+	try { const value = load(source); if (value && (typeof value !== 'object' || Array.isArray(value))) return []; }
+	catch { return []; }
+	siteRoot ??= await findNornaSiteRoot(documentPath);
+	if (!siteRoot) return [];
+	const location = getSourcePageLocation(siteRoot, path.dirname(documentPath));
+	if (!location) return [];
 	try {
-		theme = load(source) ?? {};
-	} catch {
+		const overlays = new Map(sources); overlays.set(documentPath, source);
+		const { treeTheme, selected } = await selectPageTheme({
+			siteRoot, pageDirectory: location.pageDirectory, sources: overlays,
+			includePageTheme: path.basename(documentPath) === 'page-theme.yaml',
+		});
+		const theme = path.basename(documentPath) === 'tree-theme.yaml' ? treeTheme : selected;
+		assertSectionBackgroundPatternCompatibility(theme.config, documentPath, await getNavigationModeForEditor(siteRoot));
 		return [];
+	} catch (error) {
+		const surface = error.message.includes('backgroundPattern');
+		return [{ code: surface ? 'tree-section-background-pattern' : 'invalid-resolved-theme',
+			line: surface ? findNestedYamlPropertyLine(source, 'sections', 'backgroundPattern') : 1,
+			message: error.message, severity: 'error' }];
 	}
-	if (!theme || typeof theme !== 'object' || Array.isArray(theme)) return [];
-
-	const backgroundPattern = theme.sections?.backgroundPattern;
-	if (backgroundPattern === undefined || backgroundPattern === 'uniform') return [];
-	const siteRoot = await findNornaSiteRoot(documentPath);
-	if (!siteRoot || await getNavigationModeForEditor(siteRoot) !== 'tree') return [];
-
-	return [{
-		code: 'tree-section-background-pattern',
-		line: findNestedYamlPropertyLine(source, 'sections', 'backgroundPattern'),
-		message: `sections.backgroundPattern "${backgroundPattern}" cannot be used because this site resolves to tree navigation. Tree navigation uses one uniform reading surface so the navigation rail and page content remain distinct. Remove sections.backgroundPattern or set it to uniform.`,
-		severity: 'error',
-	}];
 };
 
 const readSitewideLogoForEditor = async (siteRoot) => {
-	const filename = await findFile(siteRoot, ['sitewide-content.yaml']);
+	const filename = await findFile(siteRoot, ['site-config/shared-content.yaml']);
 	if (!filename) return null;
 	const absolutePath = path.join(siteRoot, filename);
 	const source = await readFile(absolutePath, 'utf8');
@@ -262,13 +258,14 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 const getPageContext = (siteRoot, documentPath) => {
 	const absoluteDocumentPath = path.resolve(documentPath);
 	const relativePath = toPosixPath(path.relative(siteRoot, absoluteDocumentPath));
-	const match = relativePath.match(/^pages\/(.+)\/content\.md$/);
+	if (relativePath === 'root/content.md') return { contentPath: absoluteDocumentPath, imagesRoot: getSiteSourcePaths(siteRoot).images, pageLabel: 'Home', pageDirectory: homePageDirectory };
+	const match = relativePath.match(/^root\/pages\/(.+)\/content\.md$/);
 	if (!match) return null;
 
 	const pageDirectory = match[1];
 	return {
 		contentPath: absoluteDocumentPath,
-		imagesRoot: path.join(siteRoot, 'pages', ...pageDirectory.split('/'), 'images'),
+		imagesRoot: path.join(getSiteSourcePaths(siteRoot).pages, ...pageDirectory.split('/'), 'images'),
 		pageLabel: pageDirectory,
 		pageDirectory,
 	};
@@ -492,7 +489,7 @@ const collectPageImageRoots = async (directory, siteRoot, roots) => {
 		if (!entry.isDirectory()) continue;
 		const absolutePath = path.join(directory, entry.name);
 		if (entry.name === 'images') {
-			const pageDirectory = toPosixPath(path.relative(path.join(siteRoot, 'pages'), path.dirname(absolutePath)));
+			const pageDirectory = toPosixPath(path.relative(getSiteSourcePaths(siteRoot).pages, path.dirname(absolutePath)));
 			roots.push({ imageRoot: absolutePath, pageLabel: pageDirectory });
 			continue;
 		}
@@ -515,7 +512,8 @@ const getContentFiles = async (siteRoot) => {
 		}
 	};
 
-	await visit(path.join(siteRoot, 'pages'));
+	if (await fileExists(getSiteSourcePaths(siteRoot).content)) files.push(getSiteSourcePaths(siteRoot).content);
+	await visit(getSiteSourcePaths(siteRoot).pages);
 	return files;
 };
 
@@ -534,8 +532,8 @@ const getReferencesByFilename = async (siteRoot) => {
 
 export const createSiteImageIndex = async (siteRoot) => {
 	const files = [];
-	const pageRoots = [];
-	await collectPageImageRoots(path.join(siteRoot, 'pages'), siteRoot, pageRoots);
+	const pageRoots = [{ imageRoot: getSiteSourcePaths(siteRoot).images, pageLabel: 'Home' }];
+	await collectPageImageRoots(getSiteSourcePaths(siteRoot).pages, siteRoot, pageRoots);
 	for (const root of pageRoots) {
 		await collectImageFiles(root.imageRoot, root.imageRoot, root.pageLabel, files);
 	}

package/scripts/lib/editor-page-addresses.mjs

@@ -0,0 +1,55 @@
+import { getSiteSourcePaths } from './site-conventions.mjs';
+import path from 'node:path';
+import { readEditorLinkState, isInside } from './editor-site-links.mjs';
+import { checkedPath, snapshot } from './editor-site-files.mjs';
+import { createPageMovePlan } from './page-move-plan.mjs';
+import { applyPageMovePlan } from './page-move-apply.mjs';
+
+export const siteAddressApiVersion = 1;
+
+export const getEditorPageAddresses = async (options) => {
+	const { structure, graph, settings, incomplete } = await readEditorLinkState(options);
+	const node = structure.nodes.find((entry) => (entry.contentPath ?? entry.categoryPath) === options.sourcePath);
+	if (!node) throw new Error('This page is no longer in the selected site. Refresh Site Tree.');
+	const internalLink = node.isHome ? '/' : `/${node.pagePath}/`;
+	const base = settings?.url?.replace(/\/$/, '') + '/';
+	return {
+		internalLink, webAddress: settings ? new URL(internalLink.slice(1), base).href : null,
+		segment: node.isHome ? '' : node.pageId,
+		aliases: graph.pagesByPathname.get(internalLink)?.aliases ?? [],
+		incomplete,
+	};
+};
+
+export const planEditorPageAddress = async ({ siteRoot, sourcePath, segment, sources = new Map() }) => {
+	await checkedPath(siteRoot, sourcePath);
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment)) throw new Error('Use lowercase letters, numbers and single hyphens, for example install-norna. Enter one URL segment, without slashes.');
+	const state = await readEditorLinkState({ siteRoot, sources });
+	if (state.incomplete.length) throw new Error(`Repair the site before changing an address. ${state.incomplete.join('\n')}`);
+	const node = state.structure.nodes.find((entry) => entry.contentPath === sourcePath);
+	if (!node || node.isHome) throw new Error('Choose a content page other than the homepage. Category addresses follow their folders and cannot be changed through this action.');
+	const sourcePaths = [...state.structure.nodes.map((entry) => entry.contentPath ?? entry.categoryPath), path.join(siteRoot, 'site-config/settings.yaml')];
+	if (sourcePaths.some((filename) => sources.has(filename))) throw new Error('Save or undo unsaved page, category and site-settings edits before changing an address.');
+	for (const filename of sourcePaths) await checkedPath(siteRoot, filename);
+	const to = `/${node.parentPagePath ? node.parentPagePath + '/' : ''}${segment}/`;
+	const plan = await createPageMovePlan({ from: `/${node.pagePath}/`, to,
+		graph: state.graph, publicFiles: state.publicFiles, siteStructure: state.structure,
+		sitePagesDir: getSiteSourcePaths(siteRoot).pages, sitePagesLabel: `${siteRoot}/root/pages`, generatedRoutes: state.generatedRoutes });
+	await checkedPath(siteRoot, plan.destinationDirectory);
+	const watched = [...new Set([...sourcePaths, ...state.publicFiles.map(({ filePath }) => filePath)])].sort();
+	const snapshots = [];
+	for (const filename of watched) snapshots.push([filename, await snapshot(filename)]);
+	const addresses = await getEditorPageAddresses({ siteRoot, sourcePath });
+	return { ...plan, siteRoot, sourcePath, segment, generatedRoutes: state.generatedRoutes,
+		webFrom: addresses.webAddress,
+		webTo: new URL(to.slice(1), state.settings.url.replace(/\/$/, '') + '/').href,
+		fingerprint: JSON.stringify([await snapshot(plan.sourceDirectory), snapshots, plan.to, plan.fileChanges.map(({ updatedSource }) => updatedSource)]) };
+};
+
+export const applyEditorPageAddress = async (plan, { renameDirectory } = {}) => {
+	const current = await planEditorPageAddress(plan);
+	if (current.fingerprint !== plan.fingerprint) throw new Error('The site changed after the address preview. Start again to review the new result.');
+	if (!isInside(plan.siteRoot, current.sourceDirectory) || !isInside(plan.siteRoot, current.destinationDirectory)) throw new Error('The page must remain inside its site.');
+	await applyPageMovePlan(current, { siteRoot: plan.siteRoot, generatedRoutes: current.generatedRoutes, renameDirectory });
+	return { sourcePath: path.join(current.destinationDirectory, 'content.md'), url: current.to };
+};