@janga/norna 0.7.16 → 0.7.17

package/scripts/test-documentation.mjs

@@ -12,7 +12,9 @@ const obsoleteSourceReferences = [
 	'site/config.md',
 	'site/theme.md',
 	'site/sitewide-content.md',
+	'site/routes/',
 	'route-content.md',
+	'docs/routes.md',
 	'docs/site-structure.md',
 ];
 const obsoleteSiteFilenames = new Set([
@@ -129,7 +131,10 @@ const checkObsoleteSiteFiles = async () => {
 	];
 	const files = (await Promise.all(siteRoots.map(collectFiles))).flat();
 	const obsolete = files
-		.filter((filePath) => obsoleteSiteFilenames.has(path.basename(filePath)))
+		.filter((filePath) => (
+			obsoleteSiteFilenames.has(path.basename(filePath))
+			|| filePath.split(path.sep).includes('routes')
+		))
 		.map((filePath) => path.relative(repoRoot, filePath));
 
 	assert.deepEqual(obsolete, [], `Obsolete Norna site files:\n${obsolete.join('\n')}`);

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

@@ -1,7 +1,9 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import projectContext from '../editors/vscode/norna-project.cjs';
+import yamlSchemaCompletions from '../editors/vscode/yaml-schema-completions.cjs';
 import { documentationRef } from './lib/documentation-links.mjs';
 import {
 	findNornaSiteRoot,
@@ -17,13 +19,27 @@ import {
 const root = await mkdtemp(path.join(os.tmpdir(), 'norna-editor-language-'));
 const siteRoot = path.join(root, 'site');
 const homeContentPath = path.join(siteRoot, 'content.md');
-const routeContentPath = path.join(siteRoot, 'routes', '010-about', 'content.md');
+const pageContentPath = path.join(siteRoot, 'pages', '010-about', 'content.md');
+const pageThemePath = path.join(siteRoot, 'pages', '010-about', 'theme.yaml');
+const nestedPageContentPath = path.join(siteRoot, 'pages', '010-about', 'pages', '020-team', 'content.md');
+const nestedPageThemePath = path.join(siteRoot, 'pages', '010-about', 'pages', '020-team', 'theme.yaml');
+const installedNornaRoot = path.join(root, 'node_modules', '@janga', 'norna');
+const packageManifestPath = path.join(installedNornaRoot, 'schemas', 'manifest.json');
+const {
+	getNornaDocumentContext,
+	getNornaProjectContext,
+	supportedEditorApiVersion,
+	supportedSchemaVersion,
+} = projectContext;
+const { getYamlSchemaSnippetCompletions } = yamlSchemaCompletions;
 
 const homeSource = `---
-title: Editor fixture
-description: Exercises project-local image discovery.
+page:
+  description: Exercises project-local image discovery.
 ---
 
+# Editor fixture
+
 ## Intro {#intro}
 
 Text with a missing note {note-ref}.
@@ -33,28 +49,43 @@ Text with a missing note {note-ref}.
 - image: portrait.jpg
 \`\`\`
 `;
-const routeSource = `---
-title: About
-description: About this fixture.
+const pageSource = `---
+page:
+  description: About this fixture.
 ---
 
+# About
+
 ## Team {#team}
 
-Route content.
+Page content.
 `;
 
 try {
-	await mkdir(path.join(siteRoot, 'images', 'intro'), { recursive: true });
-	await mkdir(path.join(siteRoot, 'routes', '010-about', 'images', 'team'), { recursive: true });
+	await mkdir(path.join(installedNornaRoot, 'schemas'), { recursive: true });
+	await mkdir(path.join(siteRoot, 'images'), { recursive: true });
+	await mkdir(path.join(siteRoot, 'pages', '010-about', 'images'), { recursive: true });
+	await mkdir(path.dirname(nestedPageContentPath), { recursive: true });
 	await mkdir(path.join(siteRoot, 'public'), { recursive: true });
+	await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'editor-fixture', version: '1.0.0' }));
+	await writeFile(path.join(installedNornaRoot, 'package.json'), JSON.stringify({ name: '@janga/norna', version: '9.8.7' }));
+	await writeFile(packageManifestPath, JSON.stringify({
+		editorApiVersion: supportedEditorApiVersion,
+		files: {
+			config: 'config.schema.json',
+			contentFrontmatter: 'content-frontmatter.schema.json',
+			sitewideContent: 'sitewide-content.schema.json',
+			theme: 'theme.schema.json',
+		},
+		schemaVersion: supportedSchemaVersion,
+	}));
 	await writeFile(path.join(siteRoot, 'config.yaml'), 'url: https://example.com/\n');
-	await writeFile(path.join(siteRoot, 'sitewide-content.yaml'), `navigation:
-  label: Editor fixture
-  logo:
-    height: 2rem
+	await writeFile(path.join(siteRoot, 'theme.yaml'), 'preset: project\n');
+	await writeFile(path.join(siteRoot, 'sitewide-content.yaml'), `logo:
+  height: 2rem
 `);
-	await writeFile(path.join(siteRoot, 'images', 'intro', 'local.jpg'), 'local');
-	await writeFile(path.join(siteRoot, 'routes', '010-about', 'images', 'team', 'portrait.jpg'), 'portrait');
+	await writeFile(path.join(siteRoot, 'images', 'local.jpg'), 'local');
+	await writeFile(path.join(siteRoot, 'pages', '010-about', 'images', 'portrait.jpg'), 'portrait');
 	await writeFile(path.join(siteRoot, 'public', 'logo.svg'), '<svg/>');
 	await writeFile(path.join(siteRoot, 'public', 'logo.png'), 'logo');
 	await writeFile(path.join(siteRoot, 'public', 'favicon.svg'), '<svg/>');
@@ -62,9 +93,104 @@ try {
 	await writeFile(path.join(siteRoot, 'public', 'favion.ico'), 'typo');
 	await writeFile(path.join(siteRoot, 'public', 'favicon-32x32.png'), 'unrecognized');
 	await writeFile(homeContentPath, homeSource);
-	await writeFile(routeContentPath, routeSource);
+	await writeFile(pageContentPath, pageSource);
+	await writeFile(pageThemePath, 'preset: portfolio\n');
+	await writeFile(nestedPageContentPath, pageSource.replace('# About', '# Team'));
+	await writeFile(nestedPageThemePath, 'preset: documentation\n');
 
 	assert.equal(await findNornaSiteRoot(homeContentPath), siteRoot);
+	assert.equal(getNornaDocumentContext(homeContentPath).schemaKind, 'contentFrontmatter');
+	assert.equal(getNornaDocumentContext(homeContentPath).nornaPackage.root, installedNornaRoot);
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'config.yaml')).schemaKind, 'config');
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'theme.yaml')).schemaKind, 'theme');
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'sitewide-content.yaml')).schemaKind, 'sitewideContent');
+	assert.equal(getNornaDocumentContext(pageContentPath).pageDirectory, '010-about');
+	assert.equal(getNornaDocumentContext(pageThemePath).schemaKind, 'theme');
+	assert.equal(getNornaDocumentContext(nestedPageContentPath).pageDirectory, '010-about/pages/020-team');
+	assert.equal(getNornaDocumentContext(nestedPageContentPath).schemaKind, 'contentFrontmatter');
+	assert.equal(getNornaDocumentContext(nestedPageThemePath).schemaKind, 'theme');
+	assert.equal(getNornaProjectContext(path.join(siteRoot, 'public', 'logo.svg')).siteRoot, siteRoot);
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'public', 'logo.svg')), null);
+	assert.equal(getNornaDocumentContext(path.join(root, 'README.md')), null);
+	assert.equal(getNornaDocumentContext(path.join(root, 'docs', 'content.md')), null);
+	await mkdir(path.join(siteRoot, 'pages', 'about'), { recursive: true });
+	await writeFile(path.join(siteRoot, 'pages', 'about', 'content.md'), pageSource);
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'pages', 'about', 'content.md')), null);
+	await mkdir(path.join(siteRoot, 'pages', '010-about', 'nested'), { recursive: true });
+	await writeFile(path.join(siteRoot, 'pages', '010-about', 'nested', 'content.md'), pageSource);
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'pages', '010-about', 'nested', 'content.md')), null);
+
+	const compatibleManifest = await readFile(packageManifestPath, 'utf8');
+	await writeFile(packageManifestPath, JSON.stringify({
+		...JSON.parse(compatibleManifest),
+		editorApiVersion: supportedEditorApiVersion + 1,
+	}));
+	assert.equal(getNornaDocumentContext(homeContentPath).schemaCompatible, true);
+	assert.equal(getNornaDocumentContext(homeContentPath).editorCompatible, false);
+	await writeFile(packageManifestPath, JSON.stringify({
+		...JSON.parse(compatibleManifest),
+		schemaVersion: supportedSchemaVersion + 1,
+	}));
+	assert.equal(getNornaDocumentContext(homeContentPath).schemaCompatible, false);
+	await writeFile(packageManifestPath, compatibleManifest);
+
+	const sitewideSchema = JSON.parse(await readFile(path.join(process.cwd(), 'schemas', 'sitewide-content.schema.json'), 'utf8'));
+	const bannerSource = 'banners:\n  - ';
+	const bannerSnippets = getYamlSchemaSnippetCompletions({
+		lineText: '  - ',
+		offset: bannerSource.length,
+		schema: sitewideSchema,
+		source: bannerSource,
+	});
+	assert.equal(bannerSnippets.length, 1);
+	assert.equal(bannerSnippets[0].label, 'Norna: Warning banner');
+	assert.equal(bannerSnippets[0].text, `  - id: \${1:project-status}
+    tone: warning
+    title: \${2:Important notice}
+    text: \${3:Brief explanation.}`);
+	assert.deepEqual(getYamlSchemaSnippetCompletions({
+		lineText: '  - id: existing',
+		offset: bannerSource.length,
+		schema: sitewideSchema,
+		source: bannerSource,
+	}), []);
+	const unrelatedSequence = 'other:\n  - ';
+	assert.deepEqual(getYamlSchemaSnippetCompletions({
+		lineText: '  - ',
+		offset: unrelatedSequence.length,
+		schema: sitewideSchema,
+		source: unrelatedSequence,
+	}), []);
+	const themeSchema = JSON.parse(await readFile(path.join(process.cwd(), 'schemas', 'theme.schema.json'), 'utf8'));
+	const gutterSource = 'layout:\n  gutter: ';
+	const gutterSnippets = getYamlSchemaSnippetCompletions({
+		lineText: '  gutter: ',
+		offset: gutterSource.length,
+		schema: themeSchema,
+		source: gutterSource,
+	});
+	assert.equal(gutterSnippets[0].label, 'Norna: Responsive page gutter');
+	assert.equal(gutterSnippets[0].text, `  gutter:
+    desktop: \${1:clamp(1.25rem, 4vw, 3rem)}
+    mobile: \${2:1rem}`);
+	const typographySource = 'typography:\n  overrides: ';
+	const typographySnippets = getYamlSchemaSnippetCompletions({
+		lineText: '  overrides: ',
+		offset: typographySource.length,
+		schema: themeSchema,
+		source: typographySource,
+	});
+	assert.equal(typographySnippets[0].label, 'Norna: Typography overrides');
+	assert.match(typographySnippets[0].text, /headings:\n      h2:/);
+	const buildInfoSource = 'footer:\n  buildInfo: ';
+	const buildInfoSnippets = getYamlSchemaSnippetCompletions({
+		lineText: '  buildInfo: ',
+		offset: buildInfoSource.length,
+		schema: sitewideSchema,
+		source: buildInfoSource,
+	});
+	assert.deepEqual(buildInfoSnippets, []);
+
 	const publicAssetStatus = await getSitePublicAssetStatus(homeContentPath);
 	assert.deepEqual(publicAssetStatus.logos, ['logo.png', 'logo.svg']);
 	assert.deepEqual(publicAssetStatus.browserIcons, ['favicon.svg']);
@@ -75,12 +201,14 @@ try {
 	await rm(path.join(siteRoot, 'public', 'logo.svg'), { force: true });
 	await rm(path.join(siteRoot, 'public', 'logo.png'), { force: true });
 	const missingLogoStatus = await getSitePublicAssetStatus(homeContentPath);
-	assert.ok(missingLogoStatus.issues.some(({ code, line }) => code === 'missing-logo-file' && line === 3));
+	assert.ok(missingLogoStatus.issues.some(({ code, line }) => code === 'missing-logo-file' && line === 1));
 	assert.equal(nornaBlockDefinitions['norna-image-stack'].description.includes('vertical stack'), true);
 	assert.match(
 		nornaBlockDefinitions['norna-image-stack'].documentation,
-		new RegExp(`/blob/${documentationRef.replaceAll('.', '\\.')}\/docs/content\\.md#norna-blocks`),
+		new RegExp(`/blob/${documentationRef.replaceAll('.', '\\.')}\/docs/content\\.md#image-stack`),
 	);
+	assert.match(nornaBlockDefinitions['norna-image-carousel'].documentation, /docs\/content\.md#image-carousel/);
+	assert.match(nornaBlockDefinitions['norna-card-list'].documentation, /docs\/content\.md#card-list/);
 	assert.equal(nornaBlockDefinitions['norna-card-list'].options.layout.default, 'image-top');
 
 	const stackFieldSource = homeSource.replace('- image: portrait.jpg', '- image: portrait.jpg\n  ');
@@ -116,7 +244,7 @@ try {
 		line: localDefinitionLine,
 		source: homeSource,
 	});
-	assert.deepEqual(localDefinition.files, [path.join(siteRoot, 'images', 'intro', 'local.jpg')]);
+	assert.deepEqual(localDefinition.files, [path.join(siteRoot, 'images', 'local.jpg')]);
 
 	const diagnostics = await getMarkdownDiagnostics({ documentPath: homeContentPath, source: homeSource });
 	assert.ok(diagnostics.some(({ code, message }) => code === 'image-needs-sync' && message.includes('Run "norna content:sync"')));
@@ -125,7 +253,23 @@ try {
 		documentPath: homeContentPath,
 		source: homeSource.replace('## Intro {#intro}', '## Intro'),
 	});
-	assert.ok(missingIdDiagnostics.some(({ code }) => code === 'missing-section-id'));
+	assert.equal(missingIdDiagnostics.some(({ code }) => code === 'missing-section-id'), false);
+	const duplicateIdDiagnostics = await getMarkdownDiagnostics({
+		documentPath: homeContentPath,
+		source: homeSource.replace('## Intro {#intro}', '## Intro\n\n### Intro'),
+	});
+	assert.ok(duplicateIdDiagnostics.some(({ code }) => code === 'duplicate-heading-id'));
+	const missingTitleDiagnostics = await getMarkdownDiagnostics({
+		documentPath: homeContentPath,
+		source: homeSource.replace('# Editor fixture', '## Editor fixture {#editor-fixture}'),
+	});
+	assert.ok(missingTitleDiagnostics.some(({ code }) => code === 'missing-page-title'));
+	const codeHeadingDiagnostics = await getMarkdownDiagnostics({
+		documentPath: homeContentPath,
+		source: `${homeSource}\n\`\`\`md\n# Example title\n## Example section\n\`\`\`\n`,
+	});
+	assert.equal(codeHeadingDiagnostics.some(({ code }) => code === 'duplicate-page-title'), false);
+	assert.equal(codeHeadingDiagnostics.some(({ code }) => code === 'duplicate-heading-id'), false);
 	const unclosedBlockDiagnostics = await getMarkdownDiagnostics({
 		documentPath: homeContentPath,
 		source: homeSource.replace(/\n```\n$/, '\n'),
@@ -137,14 +281,14 @@ try {
 	});
 	assert.ok(markdownImageDiagnostics.some(({ code }) => code === 'local-markdown-image'));
 
-	await writeFile(routeContentPath, routeSource.replace('Route content.', `\`\`\`norna-image-stack
+	await writeFile(pageContentPath, pageSource.replace('Page content.', `\`\`\`norna-image-stack
 - image: portrait.jpg
 \`\`\``));
 	const sharedDiagnostics = await getMarkdownDiagnostics({ documentPath: homeContentPath, source: homeSource });
 	assert.ok(sharedDiagnostics.some(({ message }) => message.includes('is still referenced by')));
 
-	await mkdir(path.join(siteRoot, 'routes', '020-contact', 'images', 'people'), { recursive: true });
-	await writeFile(path.join(siteRoot, 'routes', '020-contact', 'images', 'people', 'portrait.jpg'), 'duplicate');
+	await mkdir(path.join(siteRoot, 'pages', '020-contact', 'images'), { recursive: true });
+	await writeFile(path.join(siteRoot, 'pages', '020-contact', 'images', 'portrait.jpg'), 'duplicate');
 	const ambiguousDiagnostics = await getMarkdownDiagnostics({ documentPath: homeContentPath, source: homeSource });
 	assert.ok(ambiguousDiagnostics.some(({ message }) => message.includes('is ambiguous')));
 

package/scripts/test-engine-commands.mjs

@@ -41,7 +41,7 @@ try {
 	const directSiteRoot = path.join(tempRoot, 'current-directory-site');
 	await mkdir(directSiteRoot, { recursive: true });
 	await writeFile(path.join(directSiteRoot, 'config.yaml'), 'url: https://example.com/\n');
-	await writeFile(path.join(directSiteRoot, 'content.md'), '---\ntitle: Direct Site\ndescription: Direct site fixture.\n---\n\n## Intro {#intro}\n\nText.\n');
+	await writeFile(path.join(directSiteRoot, 'content.md'), '# Direct Site\n\n## Intro {#intro}\n\nText.\n');
 	const directSiteProjectRoot = await realpath(tempRoot);
 	const directSiteDoctorResult = runCli(['doctor'], {
 		cwd: directSiteRoot,
@@ -185,6 +185,7 @@ try {
 		"['run', 'schemas:generate']",
 		"['test']",
 		"['commit', '-m', `Release ${releaseTag}`]",
+		"['tag', '-a', releaseTag, '-m', `Release ${releaseTag}`]",
 		"['run', 'release:publish']",
 		"['push', '--follow-tags']",
 	];

package/scripts/test-heading-ids.mjs

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import {
+	formatHeadingIdentifierIssue,
+	getHeadingIdentifierIssues,
+	getMarkdownHeadings,
+	slugifyHeadingText,
+} from './lib/heading-ids.mjs';
+
+assert.equal(slugifyHeadingText('Förstå Norna'), 'forsta-norna');
+assert.equal(slugifyHeadingText('Café Über Straße'), 'cafe-uber-strasse');
+assert.equal(slugifyHeadingText('Smørrebrød & œuvre'), 'smorrebrod-oeuvre');
+assert.equal(slugifyHeadingText("What's new?"), 'whats-new');
+
+const { headings } = await getMarkdownHeadings(`# Page title
+
+## A **bold** [heading](https://example.com)
+
+### Café details
+
+## Renamed heading {#stable-id}
+
+\`\`\`md
+## Not a heading
+\`\`\`
+`);
+
+assert.deepEqual(
+	headings.map(({ depth, explicitId, id, title }) => ({ depth, explicitId, id, title })),
+	[
+		{ depth: 1, explicitId: null, id: null, title: 'Page title' },
+		{ depth: 2, explicitId: null, id: 'a-bold-heading', title: 'A bold heading' },
+		{ depth: 3, explicitId: null, id: 'cafe-details', title: 'Café details' },
+		{ depth: 2, explicitId: 'stable-id', id: 'stable-id', title: 'Renamed heading' },
+	],
+);
+assert.deepEqual(getHeadingIdentifierIssues(headings), []);
+
+const collision = await getMarkdownHeadings(`# Page
+
+## Förstå
+
+### Forsta
+`);
+assert.equal(getHeadingIdentifierIssues(collision.headings)[0]?.code, 'duplicate-heading-id');
+assert.equal(
+	formatHeadingIdentifierIssue(getHeadingIdentifierIssues(collision.headings)[0], 'site/content.md'),
+	[
+		'site/content.md: Two headings resolve to id "forsta".',
+		'- line 3: "Förstå"',
+		'- line 5: "Forsta"',
+		'Add a unique explicit id to at least one heading, for example {#forsta-details}.',
+	].join('\n'),
+);
+
+const invalid = await getMarkdownHeadings(`# Page
+
+## Symbols 🎉
+
+### 日本語
+
+## Explicit {#Not Valid}
+`);
+assert.deepEqual(
+	getHeadingIdentifierIssues(invalid.headings).map(({ code }) => code),
+	['empty-heading-id', 'invalid-heading-id'],
+);
+
+console.log('Heading id tests passed.');

package/scripts/test-navigation-model.mjs

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import {
+	getAutomaticNavigationMode,
+	navigationModeNames,
+	resolveNavigationModel,
+} from './lib/navigation-model.mjs';
+
+const home = (headings = []) => ({
+	isHome: true,
+	listed: true,
+	depth: 1,
+	headings,
+});
+const page = (headings = [], overrides = {}) => ({
+	isHome: false,
+	listed: true,
+	depth: 1,
+	headings,
+	...overrides,
+});
+const h2 = { depth: 2 };
+const h3 = { depth: 3 };
+
+assert.deepEqual(navigationModeNames, ['automatic', 'sections', 'top', 'tree']);
+assert.equal(getAutomaticNavigationMode([home([h2, h3])]), 'sections');
+assert.equal(getAutomaticNavigationMode([home([h2]), page([h2])]), 'top');
+assert.equal(getAutomaticNavigationMode([home([h2]), page([h2, h3])]), 'tree');
+assert.equal(
+	getAutomaticNavigationMode([home([h2]), page([h2, h3], { listed: false })]),
+	'sections',
+);
+assert.equal(
+	getAutomaticNavigationMode([home([h2]), page([], { depth: 2 })]),
+	'top',
+);
+assert.equal(
+	getAutomaticNavigationMode([home([h2]), page([h2], { depth: 2 })]),
+	'tree',
+);
+
+for (const mode of ['sections', 'top', 'tree']) {
+	const resolved = resolveNavigationModel({
+		mode,
+		pages: [home([h2]), page([h2, h3])],
+	});
+	assert.equal(resolved.requestedMode, mode);
+	assert.equal(resolved.mode, mode);
+}
+
+const automatic = resolveNavigationModel({
+	pages: [home([h2]), page([h2, h3])],
+});
+assert.equal(automatic.requestedMode, 'automatic');
+assert.equal(automatic.mode, 'tree');
+assert.equal(automatic.listedPageCount, 2);
+assert.equal(automatic.maximumDepth, 3);
+
+assert.throws(
+	() => resolveNavigationModel({ mode: 'sidebar', pages: [home()] }),
+	/Unknown navigation mode "sidebar".*automatic, sections, top, tree/,
+);
+
+console.log('Navigation model test passed.');

package/scripts/test-nested-pages.mjs

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { access, cp, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const repoRoot = path.resolve(import.meta.dirname, '..');
+const fixtureRoot = path.join(repoRoot, 'fixtures', 'nested-pages');
+const tempParent = path.join(repoRoot, 'node_modules', '.cache');
+await mkdir(tempParent, { recursive: true });
+const tempRoot = await mkdtemp(path.join(tempParent, 'norna-nested-pages-'));
+const fixtureCopyRoot = path.join(tempRoot, 'nested-pages');
+const nornaBin = path.join(repoRoot, 'bin', 'norna.mjs');
+const runNorna = (siteDir, ...args) => execFileAsync(process.execPath, [
+	nornaBin,
+	'--site-dir',
+	siteDir,
+	...args,
+], {
+	cwd: repoRoot,
+	maxBuffer: 1024 * 1024 * 10,
+});
+const runGit = (args) => execFileAsync('git', args, {
+	cwd: fixtureCopyRoot,
+	env: {
+		...process.env,
+		GIT_AUTHOR_NAME: 'Norna Test',
+		GIT_AUTHOR_EMAIL: 'norna@example.test',
+		GIT_COMMITTER_NAME: 'Norna Test',
+		GIT_COMMITTER_EMAIL: 'norna@example.test',
+	},
+});
+const fileExists = (filePath) => access(filePath).then(() => true, () => false);
+
+try {
+	await cp(fixtureRoot, fixtureCopyRoot, { recursive: true });
+	const siteDir = path.join(fixtureCopyRoot, 'site');
+	await runNorna(siteDir, 'content:check');
+	await runNorna(siteDir, 'build');
+
+	const distDir = path.join(fixtureCopyRoot, 'dist');
+	const expectedPages = [
+		'index.html',
+		'guides/index.html',
+		'guides/installation/index.html',
+		'guides/installation/macos/index.html',
+		'guides/workflows/index.html',
+		'reference/index.html',
+		'reference/installation/index.html',
+	];
+	for (const pagePath of expectedPages) {
+		assert.match(await readFile(path.join(distDir, pagePath), 'utf8'), /<main\b[^>]*id="main-content"/);
+	}
+
+	const rootHtml = await readFile(path.join(distDir, 'index.html'), 'utf8');
+	const guidesHtml = await readFile(path.join(distDir, 'guides', 'index.html'), 'utf8');
+	const installationHtml = await readFile(path.join(distDir, 'guides', 'installation', 'index.html'), 'utf8');
+	const macosHtml = await readFile(path.join(distDir, 'guides', 'installation', 'macos', 'index.html'), 'utf8');
+	assert.match(rootHtml, /--color-page: #000000/);
+	assert.match(guidesHtml, /--color-page: #ffffff/);
+	assert.match(installationHtml, /--color-page: #ffffff/);
+	assert.match(macosHtml, /--color-page: #ffffff/);
+	assert.match(installationHtml, /Three nested page levels connected in sequence/);
+	assert.match(installationHtml, /\/original\/pages\/010-guides\/pages\/010-installation\/images\/diagram-[a-f0-9]+\.svg/);
+	assert.match(macosHtml, /class="site-nav-item site-nav-item-has-submenu site-nav-item-current-branch"/);
+	assert.match(macosHtml, /href="\/guides\/installation\/macos\/" aria-current="page"/);
+	assert.match(macosHtml, /<details class="mobile-navigation-branch" open>/);
+	assert.match(macosHtml, /<nav class="site-breadcrumbs" aria-label="Breadcrumb"><ol><li><a href="\/guides\/">Guides<\/a><\/li><li><a href="\/guides\/installation\/">Installation<\/a><\/li><li><span aria-current="page">macOS<\/span>/);
+	for (const submenuMatch of macosHtml.matchAll(/<div class="site-nav-submenu">([\s\S]*?)<\/div>/g)) {
+		assert.doesNotMatch(submenuMatch[1], /href="[^"#]*#[^"]+"/);
+	}
+	assert.match(macosHtml, /<nav class="mobile-nav-view" aria-label="On this page">/);
+	assert.ok(
+		macosHtml.indexOf('href="/guides/installation/"') < macosHtml.indexOf('href="/guides/workflows/"'),
+		'Nested sibling navigation should follow page directory order.',
+	);
+
+	await runGit(['init']);
+	await runGit(['add', '.']);
+	await runGit(['commit', '-m', 'Initial nested fixture']);
+	const installationContentPath = path.join(
+		siteDir,
+		'pages',
+		'010-guides',
+		'pages',
+		'010-installation',
+		'content.md',
+	);
+	const workflowsContentPath = path.join(siteDir, 'pages', '010-guides', 'pages', '020-workflows', 'content.md');
+	const imageBlockPattern = /\n```norna-image-stack\n[\s\S]*?\n```\n/;
+	const installationContent = await readFile(installationContentPath, 'utf8');
+	const imageBlock = installationContent.match(imageBlockPattern)?.[0];
+	assert.ok(imageBlock, 'The nested fixture needs a managed image block to exercise content:sync.');
+	await writeFile(installationContentPath, installationContent.replace(imageBlockPattern, '\n'));
+	await writeFile(workflowsContentPath, `${await readFile(workflowsContentPath, 'utf8')}${imageBlock}`);
+	await runGit(['add', '.']);
+	await runGit(['commit', '-m', 'Move nested image reference']);
+	await runNorna(siteDir, 'content:sync', '--yes');
+
+	const previousImagePath = path.join(siteDir, 'pages', '010-guides', 'pages', '010-installation', 'images', 'diagram.svg');
+	const nextImagePath = path.join(siteDir, 'pages', '010-guides', 'pages', '020-workflows', 'images', 'diagram.svg');
+	assert.equal(await fileExists(previousImagePath), false);
+	assert.equal(await fileExists(nextImagePath), true);
+	await runNorna(siteDir, 'content:check');
+
+	console.log('Nested pages fixture check passed.');
+} finally {
+	await rm(tempRoot, { recursive: true, force: true });
+}