@janga/norna 0.7.16 → 0.7.17

package/scripts/test-package-check.mjs

@@ -168,7 +168,7 @@ try {
 		assertFileExists(path.join(packagedStarterRoot, 'site', 'theme.yaml')),
 		assertFileExists(path.join(packagedStarterRoot, 'site', 'sitewide-content.yaml')),
 		assertFileExists(path.join(packagedStarterRoot, 'site', 'content.md')),
-		assertFileExists(path.join(packagedStarterRoot, 'site', 'images', 'work', '.gitkeep')),
+		assertFileExists(path.join(packagedStarterRoot, 'site', 'images', '.gitkeep')),
 		assertFileExists(path.join(packagedStarterRoot, 'site', 'public', 'robots.txt')),
 	]);
 	await assertFileIncludes(
@@ -198,21 +198,19 @@ try {
 	const packageCheckSitewide = await readFile(packageCheckSitewidePath, 'utf8');
 	await writeFile(
 		packageCheckSitewidePath,
-		packageCheckSitewide.replace('label: Example Site', 'label: Package Check Logo\n  logo:\n    height: 2.6rem'),
+		`logo:\n  height: 2.6rem\n${packageCheckSitewide}`,
 	);
 	await writeFile(
 		path.join(siteProjectRoot, 'site', 'public', 'logo.svg'),
 		'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" fill="black"/></svg>\n',
 	);
 	await writeFile(path.join(siteProjectRoot, 'site', 'content.md'), `---
-title: Package Check Site
-description: Site used by package checks.
-sections:
-  intro: {}
-  warning: {}
-  work: {}
+page:
+  description: Site used by package checks.
 ---
 
+# Package Check Site
+
 ## Intro {#intro}
 
 This page verifies that **packaged norna sites** can build with the current content model.
@@ -230,19 +228,17 @@ This section verifies styled section headings.
 
 This section keeps the package check independent from user-facing starter copy.
 `);
-	await mkdir(path.join(siteProjectRoot, 'site', 'routes', '010-about'), { recursive: true });
-	await writeFile(path.join(siteProjectRoot, 'site', 'routes', '010-about', 'content.md'), `---
-title: About the site
-description: Route used by package checks.
-navigation:
-  label: About
-sections:
-  about: {}
+	await mkdir(path.join(siteProjectRoot, 'site', 'pages', '010-about'), { recursive: true });
+	await writeFile(path.join(siteProjectRoot, 'site', 'pages', '010-about', 'content.md'), `---
+page:
+  description: Page used by package checks.
 ---
 
+# About the site
+
 ## About {#about}
 
-This route verifies that packaged norna sites can build route pages.
+This page verifies that packaged norna sites can build additional pages.
 `);
 
 	await runInherit(npmBin, ['install', '--no-audit', '--no-fund', '--prefer-offline', '--fetch-retries=0'], { cwd: siteProjectRoot, env: npmEnv });
@@ -255,9 +251,9 @@ This route verifies that packaged norna sites can build route pages.
 		assertFileMissing(path.join(initializedSiteRoot, '.DS_Store')),
 		assertFileMissing(path.join(initializedSiteRoot, 'site', '.DS_Store')),
 	]);
-	await runInherit(npxBin, ['norna', 'engine:version'], { cwd: path.join(siteProjectRoot, 'site', 'images', 'work'), env: npmEnv });
-	await runInherit(npxBin, ['norna', 'doctor'], { cwd: path.join(siteProjectRoot, 'site', 'images', 'work'), env: npmEnv });
-	await runInherit(npxBin, ['norna', 'config:check'], { cwd: path.join(siteProjectRoot, 'site', 'images', 'work'), env: npmEnv });
+	await runInherit(npxBin, ['norna', 'engine:version'], { cwd: path.join(siteProjectRoot, 'site', 'images'), env: npmEnv });
+	await runInherit(npxBin, ['norna', 'doctor'], { cwd: path.join(siteProjectRoot, 'site', 'images'), env: npmEnv });
+	await runInherit(npxBin, ['norna', 'config:check'], { cwd: path.join(siteProjectRoot, 'site', 'images'), env: npmEnv });
 	await runInherit(npxBin, ['norna', 'content:check'], { cwd: siteProjectRoot, env: npmEnv });
 	await runInherit(npxBin, ['norna', 'check'], { cwd: siteProjectRoot, env: npmEnv });
 	await runInherit(npxBin, ['norna', 'build'], { cwd: siteProjectRoot, env: npmEnv });
@@ -315,15 +311,23 @@ This route verifies that packaged norna sites can build route pages.
 	);
 	await assertFileIncludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
-		'<a class="site-brand" href="/site/"><img class="site-brand-logo" src="/site/logo.svg" alt="Package Check Logo">',
+		'<a class="site-brand" href="/site/"><img class="site-brand-logo" src="/site/logo.svg" alt="Package Check Site">',
 	);
-	await assertFileIncludes(
+	await assertFileExcludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
 		'<div class="site-nav-submenu">',
 	);
 	await assertFileIncludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
-		'href="/site/#intro">Intro</a>',
+		'href="/site/about/">About the site</a>',
+	);
+	await assertFileIncludes(
+		path.join(siteProjectRoot, 'dist', 'index.html'),
+		'<nav class="page-nav" aria-label="On this page">',
+	);
+	await assertFileIncludes(
+		path.join(siteProjectRoot, 'dist', 'index.html'),
+		'href="#intro">Intro</a>',
 	);
 	await assertFileIncludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
@@ -367,7 +371,7 @@ This route verifies that packaged norna sites can build route pages.
 	);
 	await assertFileIncludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
-		'href="/site/#warning">Warning</a>',
+		'href="#warning">Warning</a>',
 	);
 	await assertFileIncludes(
 		path.join(siteProjectRoot, 'dist', 'index.html'),
@@ -484,28 +488,15 @@ This route verifies that packaged norna sites can build route pages.
 	await writeFile(
 		siteContentPath,
 		siteContent.replace(
-			'  intro: {}',
-			'  intro:\n    typography:\n      overrides:\n        caption:\n          spacingBefore: wide',
-		),
-	);
-	await runExpectFailure(
-		npxBin,
-		['norna', 'build'],
-		{ cwd: siteProjectRoot, env: npmEnv },
-		'sections.intro: Unrecognized key: "typography"',
-	);
-	await writeFile(
-		siteContentPath,
-		siteContent.replace(
-			'  intro: {}',
-			'  intro:\n    palette: dark',
+			'description: Site used by package checks.',
+			'description: Site used by package checks.\nsections:\n  intro: {}',
 		),
 	);
 	await runExpectFailure(
 		npxBin,
 		['norna', 'build'],
 		{ cwd: siteProjectRoot, env: npmEnv },
-		'sections.intro: Unrecognized key: "palette"',
+		'defines "sections" at the top level, but it is not a valid top-level content field',
 	);
 	await writeFile(
 		siteThemePath,

package/scripts/test-page-model.mjs

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict';
+import {
+	decodePageDirectoryPath,
+	encodePageDirectoryPath,
+	getPageDirectoryAncestors,
+	parsePageDirectory,
+	parsePageDirectoryPath,
+} from './lib/page-model.mjs';
+
+assert.deepEqual(parsePageDirectory('010-getting-started'), {
+	pageDirectory: '010-getting-started',
+	pageOrder: 10,
+	pageId: 'getting-started',
+});
+
+assert.deepEqual(parsePageDirectory('120-api-reference'), {
+	pageDirectory: '120-api-reference',
+	pageOrder: 120,
+	pageId: 'api-reference',
+});
+
+assert.deepEqual(parsePageDirectoryPath('010-guides/pages/020-installation'), {
+	pageDirectory: '010-guides/pages/020-installation',
+	pageDirectories: ['010-guides', '020-installation'],
+	pageId: 'installation',
+	pageIds: ['guides', 'installation'],
+	pageOrder: 20,
+	pageOrders: [10, 20],
+	pagePath: 'guides/installation',
+	parentPagePath: 'guides',
+	depth: 2,
+});
+
+assert.equal(
+	encodePageDirectoryPath('010-guides/pages/020-installation'),
+	'010-guides--020-installation',
+);
+assert.equal(
+	decodePageDirectoryPath('010-guides--020-installation'),
+	'010-guides/pages/020-installation',
+);
+assert.deepEqual(
+	getPageDirectoryAncestors('010-guides/pages/020-installation/pages/030-macos'),
+	[
+		'010-guides',
+		'010-guides/pages/020-installation',
+		'010-guides/pages/020-installation/pages/030-macos',
+	],
+);
+
+for (const pageDirectoryPath of [
+	'010-guides/020-installation',
+	'010-guides/children/020-installation',
+	'pages/010-guides',
+	'010-guides/pages',
+]) {
+	assert.throws(
+		() => parsePageDirectoryPath(pageDirectoryPath),
+		/(Nested pages must use|Use a pages directory)/,
+		`${pageDirectoryPath} should be rejected`,
+	);
+}
+
+for (const pageDirectory of [
+	'000-home',
+	'10-about',
+	'010_About',
+	'010-About',
+	'010-about-',
+	'010-about--team',
+	'010-om-oss!',
+]) {
+	assert.throws(
+		() => parsePageDirectory(pageDirectory),
+		/Page directories must use the form NNN-page-id/,
+		`${pageDirectory} should be rejected`,
+	);
+}
+
+console.log('Page model test passed.');

package/scripts/test-project-config.mjs

@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { getBasePathRedirectLocation } from './lib/base-path-redirect.mjs';
 
 const repoRoot = path.resolve(import.meta.dirname, '..');
 const projectConfigUrl = pathToFileURL(path.join(repoRoot, 'scripts', 'lib', 'project-config.mjs')).href;
@@ -14,6 +15,7 @@ const importScript = `
 		basePath: projectConfig.site.basePath,
 		language: projectConfig.locale.lang,
 		labels: projectConfig.locale.labels,
+		navigationMode: projectConfig.navigation.mode,
 		scrollBehavior: projectConfig.navigation.scrollBehavior,
 		url: projectConfig.site.url,
 	}));
@@ -24,7 +26,7 @@ const createSite = async (name, config) => {
 	const siteDir = path.join(projectRoot, 'site');
 	await mkdir(siteDir, { recursive: true });
 	await writeFile(path.join(siteDir, 'config.yaml'), config);
-	await writeFile(path.join(siteDir, 'content.md'), '---\ntitle: Config test\ndescription: Config test.\n---\n\n## Intro {#intro}\n\nText.\n');
+	await writeFile(path.join(siteDir, 'content.md'), '# Config test\n\n## Intro {#intro}\n\nText.\n');
 	await writeFile(path.join(siteDir, 'theme.yaml'), 'preset: documentation\n');
 	return { projectRoot, siteDir };
 };
@@ -50,6 +52,12 @@ const assertFailure = (result, expectedPattern) => {
 };
 
 try {
+	assert.equal(getBasePathRedirectLocation('/norna/', '/norna'), '/norna/');
+	assert.equal(getBasePathRedirectLocation('/norna/', '/norna?source=test'), '/norna/?source=test');
+	assert.equal(getBasePathRedirectLocation('/norna/', '/norna/'), undefined);
+	assert.equal(getBasePathRedirectLocation('/norna/', '/norna/concepts/'), undefined);
+	assert.equal(getBasePathRedirectLocation('/', '/'), undefined);
+
 	const minimalSite = await createSite('minimal', 'url: https://example.com/docs\n');
 	const minimalResult = loadConfig(minimalSite);
 	assert.equal(minimalResult.status, 0, minimalResult.stderr);
@@ -57,14 +65,20 @@ try {
 		basePath: '/docs/',
 		language: 'en',
 		labels: {
+			breadcrumb: 'Breadcrumb',
 			dismissBanner: 'Dismiss notice',
+			built: 'Built',
 			images: 'Images',
+			navigationBack: 'Back to pages',
+			navigationMenu: 'Menu',
+			navigationOverview: 'Overview',
 			note: 'Note',
 			pageNavigation: 'On this page',
 			siteBanners: 'Site notices',
 			siteNavigation: 'Pages',
 			skipToContent: 'Skip to content',
 		},
+		navigationMode: 'automatic',
 		scrollBehavior: 'instant',
 		url: 'https://example.com/docs/',
 	});
@@ -74,9 +88,19 @@ try {
 	assert.equal(localizedResult.status, 0, localizedResult.stderr);
 	const localizedConfig = JSON.parse(localizedResult.stdout);
 	assert.equal(localizedConfig.language, 'sv-SE');
+	assert.equal(localizedConfig.labels.built, 'Byggd');
 	assert.equal(localizedConfig.labels.skipToContent, 'Hoppa till innehållet');
 	assert.equal(localizedConfig.scrollBehavior, 'smooth');
 
+	const treeNavigationSite = await createSite('tree-navigation', 'url: https://example.com/\n');
+	await writeFile(path.join(treeNavigationSite.siteDir, 'theme.yaml'), `preset: documentation
+navigation:
+  mode: tree
+`);
+	const treeNavigationResult = loadConfig(treeNavigationSite);
+	assert.equal(treeNavigationResult.status, 0, treeNavigationResult.stderr);
+	assert.equal(JSON.parse(treeNavigationResult.stdout).navigationMode, 'tree');
+
 	const overrideResult = loadConfig(minimalSite, {
 		NORNA_SITE_URL: 'http://127.0.0.1:4567/preview',
 	});

package/scripts/test-schemas.mjs

@@ -15,10 +15,13 @@ const filenames = [
 ];
 const requiredRichHelp = {
 	'config.schema.json': ['url', 'language', 'scrollBehavior'],
-	'theme.schema.json': ['preset', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces'],
-	'sitewide-content.schema.json': ['navigation', 'banners', 'footer'],
-	'content-frontmatter.schema.json': ['title', 'description', 'navigation', 'sections'],
+	'theme.schema.json': ['preset', 'navigation', 'layout', 'images', 'typography', 'palette', 'sectionSurfaces'],
+	'sitewide-content.schema.json': ['logo', 'banners', 'footer'],
+	'content-frontmatter.schema.json': ['page', 'navigation'],
 };
+const manifest = JSON.parse(await readFile(path.join(root, 'schemas', 'manifest.json'), 'utf8'));
+assert.equal(manifest.editorApiVersion, 1);
+assert.equal(manifest.schemaVersion, 1);
 
 const githubHeadingAnchor = (heading) => heading
 	.toLowerCase()
@@ -49,22 +52,26 @@ const assertDocumentationLinks = async (markdownDescription, location) => {
 	}
 };
 
-const visitSchema = (schema, location) => {
+const visitSchema = (schema, location, richProperties) => {
 	assert.equal(schema.enum, undefined, `${location} uses an undescribed enum.`);
 	if (schema.properties) {
 		for (const [name, property] of Object.entries(schema.properties)) {
 			assert.ok(property.description, `${location}.${name} has no description.`);
-			visitSchema(property, `${location}.${name}`);
+			richProperties.push([property, `${location}.${name}`]);
+			visitSchema(property, `${location}.${name}`, richProperties);
 		}
 	}
-	if (schema.items) visitSchema(schema.items, `${location}[]`);
+	if (schema.items) visitSchema(schema.items, `${location}[]`, richProperties);
+	if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+		visitSchema(schema.additionalProperties, `${location}.*`, richProperties);
+	}
 	for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
 		for (const [index, candidate] of (schema[keyword] ?? []).entries()) {
 			if (Object.hasOwn(candidate, 'const')) {
 				assert.ok(candidate.title, `${location}.${keyword}[${index}] has no title.`);
 				assert.ok(candidate.description, `${location}.${keyword}[${index}] has no description.`);
 			}
-			visitSchema(candidate, `${location}.${keyword}[${index}]`);
+			visitSchema(candidate, `${location}.${keyword}[${index}]`, richProperties);
 		}
 	}
 };
@@ -83,7 +90,16 @@ for (const filename of filenames) {
 		);
 		await assertDocumentationLinks(property.markdownDescription, `${filename}.${propertyName}`);
 	}
-	visitSchema(schema, filename);
+	const richProperties = [];
+	visitSchema(schema, filename, richProperties);
+	for (const [property, location] of richProperties) {
+		assert.match(
+			property.markdownDescription,
+			/^```yaml\n/,
+			`${location} rich help must start with YAML syntax.`,
+		);
+		await assertDocumentationLinks(property.markdownDescription, location);
+	}
 }
 
 const config = JSON.parse(await readFile(path.join(root, 'schemas', 'config.schema.json'), 'utf8'));
@@ -92,11 +108,47 @@ assert.deepEqual(config.properties.language.examples, ['en', 'sv', 'en-GB', 'sv-
 assert.equal(config.properties.scrollBehavior.default, 'instant');
 
 const sitewide = JSON.parse(await readFile(path.join(root, 'schemas', 'sitewide-content.schema.json'), 'utf8'));
-assert.deepEqual(Object.keys(sitewide.properties.navigation.properties), ['label', 'logo']);
-assert.deepEqual(Object.keys(sitewide.properties.navigation.properties.logo.properties), ['height']);
-assert.match(sitewide.properties.navigation.properties.logo.markdownDescription, /```yaml\nnavigation:\n  label: Example Site\n  logo:\n    height: 2rem\n```/);
-assert.match(sitewide.properties.navigation.properties.logo.markdownDescription, /does not enable or select the file/);
-assert.match(sitewide.properties.navigation.properties.logo.markdownDescription, /docs\/public-files\.md#navigation-logo/);
-assert.equal(sitewide.properties.navigation.properties.logo.description.length < 100, true);
+assert.deepEqual(Object.keys(sitewide.properties.logo.properties), ['height']);
+assert.match(sitewide.properties.logo.markdownDescription, /```yaml\nlogo:\n  height: 2rem\n```/);
+assert.match(sitewide.properties.logo.markdownDescription, /does not enable or select the file/);
+assert.match(sitewide.properties.logo.markdownDescription, /homepage Markdown H1/);
+assert.match(sitewide.properties.logo.markdownDescription, /docs\/public-files\.md#navigation-logo/);
+assert.equal(sitewide.properties.logo.description.length < 100, true);
+const bannerItem = sitewide.properties.banners.items;
+assert.equal(bannerItem.title, 'Warning banner');
+assert.match(bannerItem.description, /important temporary information/);
+assert.match(bannerItem.markdownDescription, /A `warning` is a dismissible site-wide notice/);
+await assertDocumentationLinks(bannerItem.markdownDescription, 'sitewide-content.schema.json.banners[]');
+assert.equal(bannerItem.defaultSnippets[0].label, 'Warning banner');
+assert.deepEqual(bannerItem.defaultSnippets[0].body, {
+	id: '${1:project-status}',
+	tone: 'warning',
+	title: '${2:Important notice}',
+	text: '${3:Brief explanation.}',
+});
+await assertDocumentationLinks(
+	bannerItem.defaultSnippets[0].markdownDescription,
+	'sitewide-content.schema.json.banners[].defaultSnippets[0]',
+);
+const buildInfo = sitewide.properties.footer.properties.buildInfo;
+assert.equal(buildInfo.type, 'boolean');
+assert.equal(buildInfo.default, false);
+assert.match(buildInfo.markdownDescription, /footer:\n  buildInfo: true/);
+
+const theme = JSON.parse(await readFile(path.join(root, 'schemas', 'theme.schema.json'), 'utf8'));
+assert.equal(theme.properties.layout.properties.gutter.defaultSnippets[0].label, 'Responsive page gutter');
+assert.equal(theme.properties.layout.properties.spacing.defaultSnippets[0].label, 'Layout spacing overrides');
+assert.equal(theme.properties.typography.properties.overrides.defaultSnippets[0].label, 'Typography overrides');
+assert.equal(
+	theme.properties.images.properties.maxAvailableWidthPercent.defaultSnippets[0].label,
+	'Responsive image limit',
+);
+
+const content = JSON.parse(await readFile(path.join(root, 'schemas', 'content-frontmatter.schema.json'), 'utf8'));
+assert.deepEqual(Object.keys(content.properties), ['page', 'navigation']);
+assert.deepEqual(Object.keys(content.properties.page.properties), ['description']);
+assert.equal(content.properties.page.required, undefined);
+assert.equal(content.required, undefined);
+assert.deepEqual(Object.keys(content.properties.navigation.properties), ['listed']);
 
 console.log('Schema metadata tests passed.');

package/scripts/test-theme-presets.mjs

@@ -36,6 +36,7 @@ try {
 		const resolved = resolveThemeConfig({ preset: presetName }, 'test theme');
 		assert.equal(resolved.preset, presetName);
 		assert.ok(resolved.layout?.density);
+		assert.equal(resolved.navigation?.mode, 'automatic');
 		assert.ok(resolved.images?.width);
 		assert.ok(resolved.typography?.fontFamily);
 		assert.ok(resolved.typography?.profile);
@@ -49,6 +50,7 @@ try {
 		palette: 'dark',
 	}, 'test theme');
 	assert.equal(overridden.layout.density, 'compact');
+	assert.equal(overridden.navigation.mode, 'automatic');
 	assert.equal(overridden.layout.pageWidth, '1300px');
 	assert.equal(overridden.images.width, '920px');
 	assert.equal(overridden.palette, 'dark');
@@ -87,13 +89,15 @@ try {
 		assert.equal(entry.description, metadata.description);
 	}
 
-	await mkdir(path.join(siteDir, 'routes', '010-guide'), { recursive: true });
+	await mkdir(path.join(siteDir, 'pages', '010-guide'), { recursive: true });
 	await writeFile(path.join(siteDir, 'config.yaml'), 'url: https://example.com/\n');
 	await writeFile(path.join(siteDir, 'content.md'), `---
-title: Theme preset test
-description: Root page
+page:
+  description: Root page
 ---
 
+# Theme preset test
+
 ## Home {#home}
 
 Root content.
@@ -103,18 +107,15 @@ layout:
   pageWidth: 1300px
 palette: dark
 `);
-	await writeFile(path.join(siteDir, 'routes', '010-guide', 'content.md'), `---
-title: Guide
-description: Route page
-navigation:
-  label: Guide
+	await writeFile(path.join(siteDir, 'pages', '010-guide', 'content.md'), `---
+page:
+  description: Additional page
 ---
 
-## Guide {#guide}
-
-Route content.
+# Guide
+Page content.
 `);
-	await writeFile(path.join(siteDir, 'routes', '010-guide', 'theme.yaml'), `preset: portfolio
+	await writeFile(path.join(siteDir, 'pages', '010-guide', 'theme.yaml'), `preset: portfolio
 layout:
   pageWidth: 1010px
 palette: light
@@ -123,26 +124,33 @@ palette: light
 	const buildResult = runCli(['build']);
 	assert.equal(buildResult.status, 0, buildResult.stderr || buildResult.stdout);
 	const rootHtml = await readFile(path.join(tempRoot, 'dist', 'index.html'), 'utf8');
-	const routeHtml = await readFile(path.join(tempRoot, 'dist', 'guide', 'index.html'), 'utf8');
+	const pageHtml = await readFile(path.join(tempRoot, 'dist', 'guide', 'index.html'), 'utf8');
 	assert.match(rootHtml, /--page-width: 1300px/);
 	assert.match(rootHtml, /--font-sans: Georgia, 'Times New Roman', serif/);
 	assert.match(rootHtml, /--color-page: #000000/);
-	assert.match(routeHtml, /--page-width: 1010px/);
-	assert.match(routeHtml, /--font-sans: 'Helvetica Neue', Arial, sans-serif/);
-	assert.match(routeHtml, /--color-page: #ffffff/);
+	assert.match(pageHtml, /--page-width: 1010px/);
+	assert.match(pageHtml, /--font-sans: 'Helvetica Neue', Arial, sans-serif/);
+	assert.match(pageHtml, /--color-page: #ffffff/);
+	assert.match(rootHtml, /data-navigation-mode="top"/);
+	assert.match(pageHtml, /data-navigation-mode="top"/);
 
 	const typographyResult = runCli(['typography', 'show']);
 	assert.equal(typographyResult.status, 0, typographyResult.stderr || typographyResult.stdout);
 	assert.match(typographyResult.stdout, /value: reading/);
 	assert.match(typographyResult.stdout, /value: restrained/);
 
-	const routeThemePath = path.join(siteDir, 'routes', '010-guide', 'theme.yaml');
-	const routeThemeSource = await readFile(routeThemePath, 'utf8');
-	await writeFile(routeThemePath, 'preset: unknown\n');
-	const invalidRoutePresetResult = runCli(['config:check']);
-	assert.notEqual(invalidRoutePresetResult.status, 0);
-	assert.match(invalidRoutePresetResult.stderr, /Unknown theme preset "unknown" in .*routes\/010-guide\/theme\.yaml/);
-	await writeFile(routeThemePath, routeThemeSource);
+	const pageThemePath = path.join(siteDir, 'pages', '010-guide', 'theme.yaml');
+	const pageThemeSource = await readFile(pageThemePath, 'utf8');
+	await writeFile(pageThemePath, 'preset: unknown\n');
+	const invalidPagePresetResult = runCli(['config:check']);
+	assert.notEqual(invalidPagePresetResult.status, 0);
+	assert.match(invalidPagePresetResult.stderr, /Unknown theme preset "unknown" in .*pages\/010-guide\/theme\.yaml/);
+	await writeFile(pageThemePath, pageThemeSource);
+	await writeFile(pageThemePath, 'navigation:\n  mode: sections\n');
+	const pageNavigationResult = runCli(['config:check']);
+	assert.notEqual(pageNavigationResult.status, 0);
+	assert.match(pageNavigationResult.stderr, /page themes may not define navigation/);
+	await writeFile(pageThemePath, pageThemeSource);
 
 	const exportResult = runCli(['theme:export', 'documentation']);
 	assert.equal(exportResult.status, 0, exportResult.stderr || exportResult.stdout);
@@ -154,6 +162,7 @@ palette: light
 	assert.match(exportedSource, /# Alternatives: dark, light, paper\./);
 	const exportedConfig = load(exportedSource);
 	assert.equal(exportedConfig.preset, 'documentation');
+	assert.equal(exportedConfig.navigation.mode, 'automatic');
 	assert.equal(exportedConfig.layout.pageWidth, themePresets.documentation.layout.pageWidth);
 	assert.equal(exportedConfig.typography.fontFamily, themePresets.documentation.typography.fontFamily);
 	assert.deepEqual(exportedConfig.sectionSurfaces, ['base', 'soft']);
@@ -167,7 +176,7 @@ palette: light
 	assert.notEqual(unknownExportResult.status, 0);
 	assert.match(unknownExportResult.stderr, /Unknown theme preset "unknown"/);
 
-	console.log('ok - complete theme presets resolve for root and route themes and export as protected references');
+	console.log('ok - complete theme presets resolve for root and page themes and export as protected references');
 } finally {
 	await rm(tempRoot, { force: true, recursive: true });
 }

package/src/components/NavigationPageTree.astro

@@ -0,0 +1,68 @@
+---
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { withBasePath } from '../lib/basePath';
+import type { PageNavigationNode } from '../lib/siteNavigation';
+import type { SitePage } from '../lib/sitePages';
+
+interface Props {
+	nodes: PageNavigationNode[];
+	currentPage: SitePage;
+	variant: 'mobile' | 'submenu';
+}
+
+const { nodes, currentPage, variant } = Astro.props;
+const pageHref = (page: SitePage) => withBasePath(projectConfig.site.basePath, page.pathname);
+const hasBranch = (node: PageNavigationNode) => node.children.length > 0;
+const isCurrentPage = (page: SitePage) => page.pathname === currentPage.pathname;
+const isCurrentBranch = (page: SitePage) => (
+	page.isHome
+		? currentPage.isHome
+		: currentPage.pagePath === page.pagePath || currentPage.pagePath.startsWith(`${page.pagePath}/`)
+);
+---
+
+<ul class:list={['navigation-page-tree', `navigation-page-tree-${variant}`]}>
+	{nodes.map((node) => (
+		<li
+			class:list={['navigation-page-node', {
+				'navigation-page-node-current': isCurrentPage(node.page),
+				'navigation-page-node-current-branch': isCurrentBranch(node.page),
+			}]}
+		>
+			{variant === 'mobile' && hasBranch(node) ? (
+				<details class="mobile-navigation-branch" open={isCurrentBranch(node.page)}>
+					<summary><span>{node.page.title}</span></summary>
+					<div class="mobile-navigation-branch-content">
+						<ul class="mobile-navigation-page-links">
+							<li>
+								<a
+									class="mobile-nav-destination mobile-nav-overview"
+									href={pageHref(node.page)}
+									aria-current={isCurrentPage(node.page) ? 'page' : undefined}
+								>
+									{projectConfig.locale.labels.navigationOverview}
+								</a>
+							</li>
+						</ul>
+						{node.children.length > 0 && (
+							<Astro.self nodes={node.children} currentPage={currentPage} variant={variant} />
+						)}
+					</div>
+				</details>
+			) : (
+				<>
+					<a
+						class:list={['navigation-page-link', { 'mobile-nav-destination': variant === 'mobile' }]}
+						href={pageHref(node.page)}
+						aria-current={isCurrentPage(node.page) ? 'page' : undefined}
+					>
+						{node.page.title}
+					</a>
+					{node.children.length > 0 && (
+						<Astro.self nodes={node.children} currentPage={currentPage} variant={variant} />
+					)}
+				</>
+			)}
+		</li>
+	))}
+</ul>