@janga/norna 0.7.13 → 0.7.15

package/scripts/check-config.mjs

@@ -1,6 +1,7 @@
 import { siteConfigLabel, sitePublicLabel } from './lib/site-paths.mjs';
-import { getLogoAssets } from './lib/logo-assets.mjs';
-import { readSitewideConfig } from './lib/sitewide-config.mjs';
+import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.mjs';
+import { logoAssetFilenames } from './lib/public-asset-conventions.mjs';
+import { readSitewideContent } from './lib/sitewide-content.mjs';
 import { readThemeConfig, validateRouteThemeFiles } from './lib/theme-config.mjs';
 
 const formatErrorMessage = (error) => {
@@ -14,22 +15,28 @@ const formatErrorMessage = (error) => {
 try {
 	const { projectConfig } = await import('./lib/project-config.mjs');
 	const themeConfig = await readThemeConfig();
-	const sitewideConfig = await readSitewideConfig();
+	const sitewideContent = await readSitewideContent();
 	await validateRouteThemeFiles();
 	const logoAssets = getLogoAssets();
+	const publicAssetInspection = getPublicAssetInspection();
+	const logoAssetPaths = logoAssetFilenames.map((filename) => `${sitePublicLabel}/${filename}`);
+	for (const issue of publicAssetInspection.suspicious) {
+		console.warn(`Warning: ${sitePublicLabel}/${issue.filename}: ${issue.message}`);
+	}
 
 	if (logoAssets.length > 1) {
 		throw new Error([
-			`Found multiple logo files in ${sitePublicLabel}. Keep exactly one of logo.svg, logo.png, logo.jpg, or logo.jpeg.`,
+			`Found multiple logo files in ${sitePublicLabel}. Keep exactly one of ${logoAssetFilenames.join(', ')}.`,
 			...logoAssets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
 		].join('\n'));
 	}
 
 	if (logoAssets.length === 0) {
-		console.warn(`Warning: No logo file found in ${sitePublicLabel}. Norna will use sitewide navigation.brand or the homepage title as the navigation label.`);
-		console.warn(`Add exactly one of ${sitePublicLabel}/logo.svg, logo.png, logo.jpg, or logo.jpeg when the site should have a logo.`);
-	} else if (sitewideConfig.navigation?.brand) {
-		console.warn('Warning: Both sitewide navigation.brand and a logo file are configured. The logo is used; navigation.brand is only the text fallback.');
+		if (sitewideContent.navigation?.logo) {
+			throw new Error(`Site-wide navigation.logo is configured, but no logo file was found. Add exactly one of ${logoAssetPaths.join(', ')}, or remove navigation.logo.`);
+		}
+		console.warn(`Warning: No logo file found in ${sitePublicLabel}. Norna will use sitewide navigation.label or the homepage title as the navigation label.`);
+		console.warn(`Add exactly one of ${logoAssetPaths.join(', ')} when the site should have a logo.`);
 	}
 
 	console.log('Config check passed.');
@@ -39,9 +46,9 @@ try {
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);
 	console.log(`Layout density: ${projectConfig.layout.density}`);
-	console.log(`Image area width: ${projectConfig.gallery.width}`);
-	console.log(`Image max available width: desktop ${projectConfig.gallery.maxAvailableWidthPercent.desktop}%, mobile ${projectConfig.gallery.maxAvailableWidthPercent.mobile}%`);
-	console.log(`Image max available height: desktop ${projectConfig.gallery.maxAvailableHeightPercent.desktop}%, mobile ${projectConfig.gallery.maxAvailableHeightPercent.mobile}%`);
+	console.log(`Image area width: ${projectConfig.images.width}`);
+	console.log(`Image max available width: desktop ${projectConfig.images.maxAvailableWidthPercent.desktop}%, mobile ${projectConfig.images.maxAvailableWidthPercent.mobile}%`);
+	console.log(`Image max available height: desktop ${projectConfig.images.maxAvailableHeightPercent.desktop}%, mobile ${projectConfig.images.maxAvailableHeightPercent.mobile}%`);
 	console.log(`Font family: ${projectConfig.typography.fontFamily}`);
 	console.log(`Language: ${projectConfig.locale.lang}`);
 	console.log(`Scroll behavior: ${projectConfig.navigation.scrollBehavior}`);

package/scripts/export-theme-preset.mjs

@@ -12,7 +12,7 @@ if (!presetName || extraArgs.length > 0) {
 	throw new Error(`Usage: norna theme:export <preset>\nAvailable presets: ${themePresetNames.join(', ')}`);
 }
 
-const filename = `orig-${presetName}-theme.md`;
+const filename = `orig-${presetName}-theme.yaml`;
 const outputPath = path.join(siteDir, filename);
 const outputLabel = path.posix.join(path.posix.dirname(siteThemeLabel), filename);
 const source = renderThemePresetReference(presetName, siteThemeLabel);

package/scripts/generate-schemas.mjs

@@ -0,0 +1,283 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'astro/zod';
+import {
+	configSchema,
+	siteSchema,
+	sitewideSchema,
+	themeVisualSchema,
+} from './lib/schema-definitions.mjs';
+import { documentationLink } from './lib/documentation-links.mjs';
+import { getSchemaValueDefinition } from './lib/schema-value-definitions.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const schemaDirectory = path.join(root, 'schemas');
+const definitions = [
+	['config.schema.json', 'Norna site configuration', configSchema],
+	['theme.schema.json', 'Norna visual theme', themeVisualSchema],
+	['sitewide-content.schema.json', 'Norna site-wide content', sitewideSchema],
+	['content-frontmatter.schema.json', 'Norna page frontmatter', siteSchema],
+];
+const yamlExample = (source) => `\`\`\`yaml\n${source}\n\`\`\``;
+
+const schemaProperty = (schema, propertyPath) => {
+	let current = schema;
+	for (const name of propertyPath.split('.')) {
+		current = current?.properties?.[name];
+		if (!current) throw new Error(`Generated schema has no property at ${propertyPath}.`);
+	}
+	return current;
+};
+
+const addHelp = (schema, propertyPath, paragraphs, examples = []) => {
+	const property = schemaProperty(schema, propertyPath);
+	property.markdownDescription = paragraphs.join('\n\n');
+	if (examples.length > 0) property.examples = examples;
+};
+
+const getLiteralValues = (schema) => {
+	if (Array.isArray(schema.enum)) return schema.enum;
+	if (
+		Array.isArray(schema.anyOf)
+		&& schema.anyOf.length > 0
+		&& schema.anyOf.every((candidate) => Object.hasOwn(candidate, 'const'))
+	) {
+		return schema.anyOf.map((candidate) => candidate.const);
+	}
+	return null;
+};
+
+const addValueDescriptions = (schema) => {
+	if (!schema || typeof schema !== 'object') return;
+	if (Array.isArray(schema)) {
+		for (const value of schema) addValueDescriptions(value);
+		return;
+	}
+
+	const values = getLiteralValues(schema);
+	const definition = values ? getSchemaValueDefinition(values) : null;
+	if (definition) {
+		delete schema.enum;
+		delete schema.anyOf;
+		schema.oneOf = values.map((value) => ({
+			const: value,
+			title: definition.options[value].title,
+			description: definition.options[value].description,
+		}));
+	}
+
+	for (const value of Object.values(schema)) addValueDescriptions(value);
+};
+
+const addLanguageSuggestions = (jsonSchema) => {
+	const language = jsonSchema.properties?.language;
+	if (!language) throw new Error('Generated config schema has no language property.');
+	const definition = getSchemaValueDefinition(['en', 'sv']);
+	language.default = 'en';
+	language.examples = ['en', 'sv', 'en-GB', 'sv-SE'];
+	language.oneOf = [
+		...definition.values.map((value) => ({
+			const: value,
+			title: definition.options[value].title,
+			description: definition.options[value].description,
+		})),
+		{
+			type: 'string',
+			pattern: '^(?:en|sv)-[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$',
+			title: 'Regional language tag',
+			description: 'Use an English or Swedish regional language tag such as en-GB or sv-SE.',
+		},
+	];
+};
+
+const addSitewideNavigationHelp = (jsonSchema) => {
+	const navigation = jsonSchema.properties?.navigation;
+	const label = navigation?.properties?.label;
+	const logo = navigation?.properties?.logo;
+	if (!navigation || !label || !logo) throw new Error('Generated site-wide schema has no navigation label/logo properties.');
+
+	navigation.markdownDescription = [
+		yamlExample('navigation:\n  label: Example Site'),
+		'`navigation` defines the identity shared by the homepage and every route. Routes cannot replace it.',
+		documentationLink('Navigation identity reference', 'sitewide-content.md', 'navigation-identity'),
+	].join('\n\n');
+	label.markdownDescription = [
+		yamlExample('navigation:\n  label: Example Site'),
+		'- Without a logo, this text is shown in the navigation.',
+		'- With a logo, this text becomes the image alternative text.',
+		'- When omitted, Norna uses the homepage title.',
+		documentationLink('Navigation identity reference', 'sitewide-content.md', 'navigation-identity'),
+	].join('\n\n');
+	label.examples = ['Example Site'];
+	logo.markdownDescription = [
+		yamlExample('navigation:\n  label: Example Site\n  logo:\n    height: 2rem'),
+		'`logo` optionally overrides the displayed height of the logo file that Norna discovers automatically. It does not enable or select the file.',
+		documentationLink('Navigation logo filenames and placement', 'public-files.md', 'navigation-logo'),
+	].join('\n\n');
+	logo.properties.height.examples = ['2rem'];
+};
+
+const addConfigHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('url: https://example.com/'),
+		'`config.yaml` contains the few technical settings shared by the complete site.',
+		documentationLink('Configuration reference', 'configuration.md'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'url', [
+		yamlExample('url: https://example.com/'),
+		'The absolute public URL. Its path also determines the base path for generated links and assets.',
+		documentationLink('Public URL reference', 'configuration.md', 'url'),
+	], ['https://example.com/', 'https://owner.github.io/repository-name/']);
+	addHelp(jsonSchema, 'language', [
+		yamlExample('language: en-GB'),
+		'Sets the page language and selects Norna\'s built-in English or Swedish interface text. The default is `en`.',
+		documentationLink('Language reference', 'configuration.md', 'language'),
+	], ['en', 'sv', 'en-GB', 'sv-SE']);
+	addHelp(jsonSchema, 'scrollBehavior', [
+		yamlExample('scrollBehavior: smooth'),
+		'Controls same-page anchor movement. `instant` is the default; `smooth` uses the browser\'s native smooth scrolling.',
+		documentationLink('Scroll behavior reference', 'configuration.md', 'scrollbehavior'),
+	], ['instant', 'smooth']);
+};
+
+const addThemeHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('preset: documentation'),
+		'Choose one complete preset first. Add focused overrides only when the site needs to differ from it.',
+		documentationLink('Theme reference', 'theme.md'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'preset', [
+		yamlExample('preset: documentation'),
+		'Selects coordinated layout, image sizing, typography, palette and section surfaces. This is the normal starting point for a theme.',
+		documentationLink('Compare theme presets', 'theme.md', 'theme-presets'),
+	]);
+	addHelp(jsonSchema, 'layout', [
+		yamlExample('layout:\n  density: compact\n  pageWidth: 72rem'),
+		'Overrides page width, gutters and structural spacing after the selected preset.',
+		documentationLink('Layout reference', 'theme.md', 'layout'),
+	]);
+	addHelp(jsonSchema, 'images', [
+		yamlExample('images:\n  width: 900px\n  maxAvailableHeightPercent: 74'),
+		'Overrides the available width and height used by Norna-managed images.',
+		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
+	]);
+	addHelp(jsonSchema, 'typography', [
+		yamlExample('typography:\n  profile: reading\n  rhythm: normal'),
+		'Overrides the preset\'s font stack, typography profile, rhythm or individual text settings.',
+		documentationLink('Typography configuration reference', 'typography.md', 'configuration-shape'),
+	]);
+	addHelp(jsonSchema, 'palette', [
+		yamlExample('palette: paper'),
+		'Chooses a coordinated color system for the page frame, navigation, footer and section surfaces.',
+		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
+	], ['dark', 'light', 'paper']);
+	addHelp(jsonSchema, 'sectionSurfaces', [
+		yamlExample('sectionSurfaces: [base, soft, emphasis]'),
+		'Lists one to three semantic surfaces. Norna cycles through them in section order; omit this field to keep the preset sequence.',
+		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
+	], [['base'], ['base', 'soft'], ['base', 'soft', 'emphasis']]);
+};
+
+const addSitewideHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('navigation:\n  label: Example Site'),
+		'`sitewide-content.yaml` optionally defines editorial content and identity shared by every page.',
+		documentationLink('Site-wide content reference', 'sitewide-content.md'),
+	].join('\n\n');
+	addSitewideNavigationHelp(jsonSchema);
+	addHelp(jsonSchema, 'banners', [
+		yamlExample('banners:\n  - id: project-status\n    tone: warning\n    title: Experimental code\n    text: Not for production use.'),
+		'Adds dismissible notices above page content. List order controls their presentation order; each `id` must be unique.',
+		documentationLink('Banner reference', 'sitewide-content.md', 'banners'),
+	]);
+	addHelp(jsonSchema, 'footer', [
+		yamlExample('footer:\n  copyrightMessage: Copyright Example Owner.'),
+		'Adds shared footer content. Generated build information is optional.',
+		documentationLink('Footer reference', 'sitewide-content.md', 'footer'),
+	]);
+};
+
+const addContentHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('---\ntitle: About\ndescription: About this project.\n---'),
+		'Every homepage and route `content.md` starts with page metadata, followed by Markdown sections.',
+		documentationLink('Page frontmatter reference', 'content.md', 'page-frontmatter'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'title', [
+		yamlExample('title: About'),
+		'The page title used in metadata and, by default, route navigation.',
+		documentationLink('Page frontmatter reference', 'content.md', 'page-frontmatter'),
+	], ['About']);
+	addHelp(jsonSchema, 'description', [
+		yamlExample('description: About this project.'),
+		'A concise page description used in metadata.',
+		documentationLink('Page frontmatter reference', 'content.md', 'page-frontmatter'),
+	], ['About this project.']);
+	addHelp(jsonSchema, 'navigation', [
+		yamlExample('navigation:\n  include: true\n  label: About us'),
+		'Controls whether a route appears in site navigation and optionally replaces its visible title there. Homepage navigation is section-based.',
+		documentationLink('Route navigation reference', 'routes.md', 'navigation'),
+	]);
+	addHelp(jsonSchema, 'sections', [
+		yamlExample('sections:\n  announcement:\n    visible:\n      until: "2026-12-01"'),
+		'Adds optional metadata keyed by explicit Markdown section id. Markdown headings remain the source of section content and order.',
+		documentationLink('Section metadata reference', 'content.md', 'section-metadata'),
+	]);
+};
+
+const schemaFiles = new Map();
+
+for (const [filename, title, schema] of definitions) {
+	const jsonSchema = z.toJSONSchema(schema, { target: 'draft-07', io: 'input' });
+	jsonSchema.$id = `https://janga.github.io/norna/schemas/${filename}`;
+	jsonSchema.title = title;
+	addValueDescriptions(jsonSchema);
+	if (filename === 'config.schema.json') {
+		addLanguageSuggestions(jsonSchema);
+		addConfigHelp(jsonSchema);
+	}
+	if (filename === 'theme.schema.json') addThemeHelp(jsonSchema);
+	if (filename === 'sitewide-content.schema.json') addSitewideHelp(jsonSchema);
+	if (filename === 'content-frontmatter.schema.json') addContentHelp(jsonSchema);
+	schemaFiles.set(filename, `${JSON.stringify(jsonSchema, null, 2)}\n`);
+}
+
+schemaFiles.set('manifest.json', `${JSON.stringify({
+	schemaVersion: 1,
+	files: {
+		config: 'config.schema.json',
+		contentFrontmatter: 'content-frontmatter.schema.json',
+		sitewideContent: 'sitewide-content.schema.json',
+		theme: 'theme.schema.json',
+	},
+}, null, 2)}\n`);
+
+const args = process.argv.slice(2);
+const checkOnly = args.length === 1 && args[0] === '--check';
+if (args.length > 0 && !checkOnly) {
+	throw new Error('Usage: node scripts/generate-schemas.mjs [--check]');
+}
+
+if (checkOnly) {
+	const stale = [];
+	for (const [filename, expected] of schemaFiles) {
+		const actual = await readFile(path.join(schemaDirectory, filename), 'utf8').catch((error) => (
+			error?.code === 'ENOENT' ? null : Promise.reject(error)
+		));
+		if (actual !== expected) stale.push(filename);
+	}
+
+	if (stale.length > 0) {
+		throw new Error(`Generated Norna schemas are stale: ${stale.join(', ')}. Run "npm run schemas:generate".`);
+	}
+
+	console.log(`Norna schemas are up to date (${definitions.length} schemas).`);
+} else {
+	await mkdir(schemaDirectory, { recursive: true });
+	for (const [filename, source] of schemaFiles) {
+		await writeFile(path.join(schemaDirectory, filename), source);
+	}
+
+	console.log(`Generated ${definitions.length} Norna schemas in ${path.relative(root, schemaDirectory)}.`);
+}

package/scripts/init-site.mjs

@@ -11,14 +11,14 @@ const packageName = '@janga/norna';
 const cliExecutableName = 'norna';
 
 const usage = `
-Usage: norna init <target-dir> [--type pure|embedded] [--site-dir <path>]
+Usage: norna init <target-dir> [--type standalone|embedded] [--site-dir <path>]
 
 Creates a new site project or adds a Norna site directory to an existing
 project.
 
 Examples:
   norna init my-site
-  norna init my-site --type pure
+  norna init my-site --type standalone
   norna init . --type embedded --site-dir presentation
 `.trim();
 
@@ -27,7 +27,7 @@ const parseArgs = (rawArgs) => {
 	const options = {
 		siteDirectory: process.env[siteDirectoryEnv] ?? 'site',
 		targetDirectory: null,
-		type: 'pure',
+		type: 'standalone',
 	};
 
 	for (let index = 0; index < rawArgs.length; index += 1) {
@@ -36,7 +36,7 @@ const parseArgs = (rawArgs) => {
 		if (arg === '--type') {
 			const value = rawArgs[index + 1];
 			if (!value || value.startsWith('-')) {
-				throw new Error('--type requires "pure" or "embedded".');
+				throw new Error('--type requires "standalone" or "embedded".');
 			}
 			options.type = value;
 			index += 1;
@@ -87,8 +87,8 @@ if (!targetDirectory) {
 	throw new Error(usage);
 }
 
-if (!['pure', 'embedded'].includes(type)) {
-	throw new Error(`Invalid --type "${type}". Use "pure" or "embedded".`);
+if (!['standalone', 'embedded'].includes(type)) {
+	throw new Error(`Invalid --type "${type}". Use "standalone" or "embedded".`);
 }
 
 if (!siteDirectory || path.isAbsolute(siteDirectory) || siteDirectory.split(/[\\/]/).includes('..')) {
@@ -122,19 +122,20 @@ const readJsonFile = async (filePath) => JSON.parse(await readFile(filePath, 'ut
 
 const siteDirArg = siteDirectory === 'site' ? [] : ['--site-dir', siteDirectory];
 const cliCommand = (command) => [cliExecutableName, ...siteDirArg, command].join(' ');
-const galleryScripts = {
+const nornaScripts = {
 	'norna:dev': cliCommand('dev:local'),
 	'norna:dev:lan': cliCommand('dev:lan'),
 	'norna:dev:restart': cliCommand('dev:restart'),
 	'norna:dev:status': cliCommand('dev:status'),
 	'norna:dev:logs': cliCommand('dev:logs'),
 	'norna:dev:stop': cliCommand('dev:stop'),
-	'norna:check': 'npm run norna:config:check && npm run norna:content:check',
+	'norna:check': cliCommand('check'),
 	'norna:config:check': cliCommand('config:check'),
 	'norna:content:check': cliCommand('content:check'),
 	'norna:sync': cliCommand('content:sync'),
+	'norna:theme:presets': cliCommand('theme:presets'),
 	'norna:theme:export': cliCommand('theme:export'),
-	'norna:typography:presets': cliCommand('typography presets'),
+	'norna:typography:profiles': cliCommand('typography profiles'),
 	'norna:typography:show': cliCommand('typography show'),
 	'norna:public': cliCommand('site:public'),
 	'norna:images': cliCommand('images'),
@@ -149,17 +150,17 @@ const galleryScripts = {
 	'norna:engine:version': cliCommand('engine:version'),
 };
 
-const addGalleryDependency = (packageJson, version) => {
+const addNornaDependency = (packageJson, version) => {
 	packageJson.dependencies ??= {};
 	packageJson.dependencies[packageName] ??= version;
 };
 
-const addGalleryScripts = (packageJson, scripts, { includePureAliases }) => {
+const addNornaScripts = (packageJson, scripts, { includeStandaloneAliases }) => {
 	packageJson.scripts ??= {};
 	const wantedScripts = {
-		...(includePureAliases ? { dev: 'npm run norna:dev --' } : {}),
+		...(includeStandaloneAliases ? { dev: 'npm run norna:dev --' } : {}),
 		...scripts,
-		...(includePureAliases ? { build: 'npm run norna:build' } : {}),
+		...(includeStandaloneAliases ? { build: 'npm run norna:build' } : {}),
 	};
 	const conflicts = Object.entries(wantedScripts).filter(([name, value]) => (
 		packageJson.scripts[name] !== undefined && packageJson.scripts[name] !== value
@@ -178,12 +179,12 @@ const addGalleryScripts = (packageJson, scripts, { includePureAliases }) => {
 const enginePackageJson = await readJsonFile(enginePackageJsonPath);
 const existingEntries = await readDirectoryEntries(targetRoot);
 
-if (type === 'pure') {
+if (type === 'standalone') {
 	if (existingEntries && existingEntries.length > 0) {
 		const existingPackageJson = existingEntries.includes('package.json')
 			? ' The target already contains package.json; use --type embedded to add a Norna site to an existing project.'
 			: '';
-		throw new Error(`Target directory must be empty for --type pure: ${targetRoot}.${existingPackageJson}`);
+		throw new Error(`Target directory must be empty for --type standalone: ${targetRoot}.${existingPackageJson}`);
 	}
 
 	await mkdir(path.dirname(targetRoot), { recursive: true });
@@ -199,10 +200,8 @@ if (type === 'pure') {
 
 	const targetPackageJson = await readJsonFile(targetPackageJsonPath);
 	targetPackageJson.dependencies[packageName] = enginePackageJson.version;
-	if (siteDirectory !== 'site') {
-		targetPackageJson.scripts = {};
-		addGalleryScripts(targetPackageJson, galleryScripts, { includePureAliases: true });
-	}
+	if (siteDirectory !== 'site') targetPackageJson.scripts = {};
+	addNornaScripts(targetPackageJson, nornaScripts, { includeStandaloneAliases: true });
 	await writeFile(targetPackageJsonPath, `${JSON.stringify(targetPackageJson, null, 2)}\n`);
 } else {
 	if (!existingEntries) {
@@ -222,8 +221,8 @@ if (type === 'pure') {
 		throw new Error(`Norna site directory must be empty for --type embedded: ${targetSiteDir}`);
 	}
 
-	addGalleryDependency(targetPackageJson, enginePackageJson.version);
-	addGalleryScripts(targetPackageJson, galleryScripts, { includePureAliases: false });
+	addNornaDependency(targetPackageJson, enginePackageJson.version);
+	addNornaScripts(targetPackageJson, nornaScripts, { includeStandaloneAliases: false });
 	await mkdir(path.dirname(targetSiteDir), { recursive: true });
 	await cp(starterSiteRoot, targetSiteDir, {
 		filter: (source) => path.basename(source) !== '.DS_Store',
@@ -244,9 +243,5 @@ if (isInsideEngineRoot(targetRoot)) {
 console.log('');
 console.log('Next steps:');
 console.log(`  cd ${targetRoot}`);
-console.log(type === 'embedded'
-	? '  npm install'
-	: '  npm install');
-console.log(type === 'embedded'
-	? '  npm run norna:dev'
-	: '  npm run dev');
+console.log('  npm install');
+console.log('  npm run norna:dev');

package/scripts/lib/documentation-links.mjs

@@ -0,0 +1,8 @@
+import packageJson from '../../package.json' with { type: 'json' };
+
+export const documentationRef = `v${packageJson.version}`;
+export const documentationRoot = `https://github.com/janga/norna/blob/${documentationRef}/docs`;
+
+export const documentationLink = (label, file, anchor) => (
+	`[${label}](${documentationRoot}/${file}${anchor ? `#${anchor}` : ''})`
+);