@janga/norna 0.7.16 → 0.7.18

package/scripts/test-documentation.mjs

@@ -9,10 +9,14 @@ const cliPath = path.join(repoRoot, 'bin', 'norna.mjs');
 const tutorialPath = path.join(repoRoot, 'docs', 'getting-started.md');
 const scratchRoot = path.join(repoRoot, 'todos');
 const obsoleteSourceReferences = [
+	'site/content.md',
+	'site/images/',
 	'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 +133,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')}`);
@@ -144,8 +151,8 @@ try {
 
 	await Promise.all([
 		writeFile(
-			path.join(tutorialSiteRoot, 'site', 'content.md'),
-			extractTutorialFile(tutorial, 'Replace `site/content.md` with:', 'md'),
+			path.join(tutorialSiteRoot, 'site', 'pages', '000-home', 'content.md'),
+			extractTutorialFile(tutorial, 'Replace `site/pages/000-home/content.md` with:', 'md'),
 		),
 		writeFile(
 			path.join(tutorialSiteRoot, 'site', 'sitewide-content.yaml'),

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,
@@ -16,14 +18,28 @@ 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 homeContentPath = path.join(siteRoot, 'pages', '000-home', '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,44 @@ 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, 'pages', '000-home', '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',
+			pageTheme: 'page-theme.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, 'pages', '000-home', '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 +94,106 @@ 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, 'layout:\n  textWidth: wide\n');
+	await writeFile(nestedPageContentPath, pageSource.replace('# About', '# Team'));
+	await writeFile(nestedPageThemePath, 'layout:\n  contentSpacing: compact\n');
 
 	assert.equal(await findNornaSiteRoot(homeContentPath), siteRoot);
+	assert.equal(getNornaDocumentContext(homeContentPath).schemaKind, 'contentFrontmatter');
+	assert.equal(getNornaDocumentContext(homeContentPath).pageDirectory, '000-home');
+	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, 'pageTheme');
+	assert.equal(getNornaDocumentContext(nestedPageContentPath).pageDirectory, '010-about/pages/020-team');
+	assert.equal(getNornaDocumentContext(nestedPageContentPath).schemaKind, 'contentFrontmatter');
+	assert.equal(getNornaDocumentContext(nestedPageThemePath).schemaKind, 'pageTheme');
+	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);
+	assert.equal(getNornaDocumentContext(path.join(siteRoot, 'pages', '000-home', 'pages', '010-news', '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 +204,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 +247,7 @@ try {
 		line: localDefinitionLine,
 		source: homeSource,
 	});
-	assert.deepEqual(localDefinition.files, [path.join(siteRoot, 'images', 'intro', 'local.jpg')]);
+	assert.deepEqual(localDefinition.files, [path.join(siteRoot, 'pages', '000-home', '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 +256,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 +284,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

@@ -39,9 +39,9 @@ try {
 	assert.match(deployWatchHelpResult.stdout, /Default: deploy\.yml/);
 
 	const directSiteRoot = path.join(tempRoot, 'current-directory-site');
-	await mkdir(directSiteRoot, { recursive: true });
+	await mkdir(path.join(directSiteRoot, 'pages', '000-home'), { 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, 'pages', '000-home', 'content.md'), '# Direct Site\n\n## Intro {#intro}\n\nText.\n');
 	const directSiteProjectRoot = await realpath(tempRoot);
 	const directSiteDoctorResult = runCli(['doctor'], {
 		cwd: directSiteRoot,
@@ -99,7 +99,7 @@ try {
 	assert.match(showResult.stdout, /theme:/);
 	assert.match(showResult.stdout, /pages:/);
 	assert.match(showResult.stdout, /\s+\/:/);
-	assert.match(showResult.stdout, /value: restrained/);
+	assert.match(showResult.stdout, /value: reading/);
 	assert.match(showResult.stdout, /source: "site\/theme\.yaml"/);
 	assert.match(showResult.stdout, /intro:/);
 
@@ -116,7 +116,7 @@ try {
 	assert.equal(customStandalonePackageJson.scripts['norna:dev'], 'norna --site-dir presentation dev:local');
 	assert.equal(customStandalonePackageJson.scripts['norna:check'], 'norna --site-dir presentation check');
 	assert.equal(customStandalonePackageJson.scripts['norna:build'], 'norna --site-dir presentation build');
-	await readFile(path.join(customStandaloneSiteRoot, 'presentation', 'content.md'));
+	await readFile(path.join(customStandaloneSiteRoot, 'presentation', 'pages', '000-home', 'content.md'));
 	await readFile(path.join(customStandaloneSiteRoot, 'presentation', 'config.yaml'));
 	await readFile(path.join(customStandaloneSiteRoot, 'presentation', 'theme.yaml'));
 
@@ -143,7 +143,7 @@ try {
 	assert.equal(mixedPackageJson.scripts['norna:check'], 'norna --site-dir presentation check');
 	assert.equal(mixedPackageJson.scripts['norna:engine:update'], 'norna --site-dir presentation engine:update');
 	assert.equal(mixedPackageJson.scripts['norna:engine:version'], 'norna --site-dir presentation engine:version');
-	await readFile(path.join(mixedProjectRoot, 'presentation', 'content.md'));
+	await readFile(path.join(mixedProjectRoot, 'presentation', 'pages', '000-home', 'content.md'));
 	await readFile(path.join(mixedProjectRoot, 'presentation', 'config.yaml'));
 	await readFile(path.join(mixedProjectRoot, 'presentation', 'theme.yaml'));
 
@@ -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-examples.mjs

@@ -1,5 +1,7 @@
+import assert from 'node:assert/strict';
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getExampleSites } from './lib/example-sites.mjs';
@@ -9,6 +11,33 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const cliPath = path.join(root, 'bin', 'norna.mjs');
 const examples = await getExampleSites(root);
 
+const discoveryRoot = await mkdtemp(path.join(tmpdir(), 'norna-example-discovery-'));
+try {
+	for (const category of ['complete-sites', 'feature-demos']) {
+		await mkdir(path.join(discoveryRoot, 'examples', category), { recursive: true });
+	}
+	const validSite = path.join(discoveryRoot, 'examples', 'complete-sites', 'valid', 'site');
+	await mkdir(path.join(validSite, 'pages', '000-home'), { recursive: true });
+	await writeFile(path.join(validSite, 'config.yaml'), 'url: https://example.com/\n');
+	await writeFile(path.join(validSite, 'pages', '000-home', 'content.md'), '# Example\n');
+	await mkdir(path.join(
+		discoveryRoot,
+		'examples',
+		'feature-demos',
+		'removed-example',
+		'site',
+		'.norna',
+		'public',
+		'images',
+		'generated',
+	), { recursive: true });
+
+	const discovered = await getExampleSites(discoveryRoot);
+	assert.deepEqual(discovered.map(({ name }) => name), ['valid']);
+} finally {
+	await rm(discoveryRoot, { recursive: true, force: true });
+}
+
 for (const example of examples) {
 	console.log(`\nBuilding ${example.siteLabel}`);
 	await runInherit(process.execPath, [cliPath, '--site-dir', example.siteLabel, 'build'], { cwd: root });

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/pages/000-home/content.md'),
+	[
+		'site/pages/000-home/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-navigation.mjs

@@ -5,10 +5,19 @@ import { fileURLToPath } from 'node:url';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const cliPath = path.join(root, 'bin', 'norna.mjs');
-const navigationDemoSiteDir = path.join(root, 'examples', 'feature-demos', 'media-and-surfaces', 'site');
 const host = '127.0.0.1';
 const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-const testTargets = process.argv.slice(2);
+const cliArguments = process.argv.slice(2);
+const siteDirOptionIndex = cliArguments.indexOf('--site-dir');
+const configuredSiteDir = siteDirOptionIndex === -1
+	? path.join('examples', 'feature-demos', 'media-and-surfaces', 'site')
+	: cliArguments[siteDirOptionIndex + 1];
+if (!configuredSiteDir || configuredSiteDir.startsWith('--')) {
+	throw new Error('Use --site-dir <path> to select a navigation test site.');
+}
+if (siteDirOptionIndex !== -1) cliArguments.splice(siteDirOptionIndex, 2);
+const navigationDemoSiteDir = path.resolve(root, configuredSiteDir);
+const testTargets = cliArguments;
 const playwrightTargets = testTargets.length > 0 ? testTargets : ['tests/navigation.spec.ts'];
 
 const sleep = (milliseconds) => new Promise((resolve) => {