@janga/norna 0.7.23 → 0.7.24

package/scripts/build-site.mjs

@@ -14,3 +14,4 @@ await runScript('scripts/sync-content-sections.mjs', ['--check']);
 await runScript('scripts/sync-site-public.mjs');
 await runScript('scripts/generate-images.mjs');
 await runAstroInherit(['build']);
+await runScript('scripts/generate-search-index.mjs');

package/scripts/check-config.mjs

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { siteConfigLabel, sitePagesDir, sitePublicLabel, siteThemeLabel } from './lib/site-paths.mjs';
 import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.mjs';
-import { logoAssetFilenames } from './lib/public-asset-conventions.mjs';
+import { logoAssetFilenames, socialImageAssetFilenames } from './lib/public-asset-conventions.mjs';
+import { getSocialImageAssets } from './lib/social-image-assets.mjs';
 import { readSitewideContent } from './lib/sitewide-content.mjs';
 import { assertSectionBackgroundPatternCompatibility } from './lib/presentation.mjs';
 import { readThemeConfig, validatePageThemeFiles } from './lib/theme-config.mjs';
@@ -43,6 +44,7 @@ try {
 		}
 	}
 	const logoAssets = getLogoAssets();
+	const socialImageAssets = getSocialImageAssets();
 	const publicAssetInspection = getPublicAssetInspection();
 	const logoAssetPaths = logoAssetFilenames.map((filename) => `${sitePublicLabel}/${filename}`);
 	for (const issue of publicAssetInspection.suspicious) {
@@ -56,6 +58,13 @@ try {
 		].join('\n'));
 	}
 
+	if (socialImageAssets.length > 1) {
+		throw new Error([
+			`Found multiple social sharing images in ${sitePublicLabel}. Keep exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+			...socialImageAssets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
+		].join('\n'));
+	}
+
 	if (logoAssets.length === 0) {
 		if (sitewideContent.logo) {
 			throw new Error(`Site-wide logo is configured, but no logo file was found. Add exactly one of ${logoAssetPaths.join(', ')}, or remove logo.`);
@@ -67,6 +76,7 @@ try {
 	console.log('Config check passed.');
 	console.log(`Site URL: ${projectConfig.site.url}`);
 	console.log(`Base path: ${projectConfig.site.basePath}`);
+	console.log(`Edit links: ${projectConfig.editLink?.baseUrl ?? '(disabled)'}`);
 	console.log(`Theme preset: ${themeConfig.preset ?? '(none)'}`);
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);
@@ -81,6 +91,7 @@ try {
 	console.log(`Font family: ${projectConfig.typography.fontFamily}`);
 	console.log(`Language: ${projectConfig.locale.lang}`);
 	console.log(`Navigation mode: ${projectConfig.navigation.mode}`);
+	console.log(`Static search: ${projectConfig.search.enabled ? 'enabled' : 'disabled'}`);
 	console.log(`Scroll behavior: ${projectConfig.navigation.scrollBehavior}`);
 } catch (error) {
 	console.error('Config check failed.');

package/scripts/generate-search-index.mjs

@@ -0,0 +1,57 @@
+import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import * as pagefind from 'pagefind';
+import projectConfig from './lib/project-config.mjs';
+import {
+	astroDistDir,
+	astroPublicDir,
+} from './lib/site-paths.mjs';
+
+const searchDirectoryName = 'pagefind';
+const distSearchDirectory = path.join(astroDistDir, searchDirectoryName);
+const localSearchDirectory = path.join(astroPublicDir, searchDirectoryName);
+
+if (!projectConfig.search.enabled) {
+	await rm(localSearchDirectory, { force: true, recursive: true });
+	console.log('Static search is disabled.');
+} else {
+	await rm(distSearchDirectory, { force: true, recursive: true });
+
+	try {
+		const { errors: createErrors, index } = await pagefind.createIndex();
+		if (!index || createErrors.length > 0) {
+			throw new Error(createErrors.join('\n') || 'Pagefind did not create an index.');
+		}
+
+		const { errors: indexingErrors, page_count: scannedPageCount } = await index.addDirectory({
+			path: astroDistDir,
+		});
+		if (indexingErrors.length > 0) throw new Error(indexingErrors.join('\n'));
+		if (scannedPageCount === 0) {
+			throw new Error('No rendered pages contained searchable editorial content.');
+		}
+
+		const { errors: writeErrors } = await index.writeFiles({
+			outputPath: distSearchDirectory,
+		});
+		if (writeErrors.length > 0) throw new Error(writeErrors.join('\n'));
+		const fragmentDirectory = path.join(distSearchDirectory, 'fragment');
+		const indexedPageCount = (await readdir(fragmentDirectory))
+			.filter((filename) => filename.endsWith('.pf_fragment'))
+			.length;
+		if (indexedPageCount === 0) {
+			throw new Error('No rendered pages contained searchable editorial content.');
+		}
+
+		await rm(localSearchDirectory, { force: true, recursive: true });
+		await mkdir(astroPublicDir, { recursive: true });
+		await cp(distSearchDirectory, localSearchDirectory, { recursive: true });
+
+		console.log(`Generated static search index for ${indexedPageCount} page${indexedPageCount === 1 ? '' : 's'}.`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not generate the static search index. ${message}`);
+	} finally {
+		await pagefind.close();
+	}
+}

package/scripts/init-site.mjs

@@ -165,6 +165,7 @@ const nornaScripts = {
 	'norna:config:check': cliCommand('config:check'),
 	'norna:content:check': cliCommand('content:check'),
 	'norna:sync': cliCommand('content:sync'),
+	'norna:navigation:review': cliCommand('navigation:review'),
 	'norna:theme:presets': cliCommand('theme:presets'),
 	'norna:theme:export': cliCommand('theme:export'),
 	'norna:typography:profiles': cliCommand('typography profiles'),

package/scripts/lib/code-fence-metadata.mjs

@@ -0,0 +1,223 @@
+const titlePrefix = 'title="';
+const lineSelectorPattern = /^\{(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)\}$/;
+
+const invalidMetadata = (message, fix) => ({
+	error: {
+		code: 'invalid-code-fence-metadata',
+		fix,
+		message,
+	},
+});
+
+const parseTitle = (source) => {
+	let title = '';
+	let index = titlePrefix.length;
+
+	while (index < source.length) {
+		const character = source[index];
+		if (character === '"') {
+			return {
+				rest: source.slice(index + 1),
+				title,
+			};
+		}
+
+		if (character === '\\') {
+			const escaped = source[index + 1];
+			if (escaped !== '"' && escaped !== '\\') {
+				return invalidMetadata(
+					`Code title contains unsupported escape "\\${escaped ?? ''}".`,
+					'Only escape a double quote (\\") or backslash (\\\\) inside the title.',
+				);
+			}
+			title += escaped;
+			index += 2;
+			continue;
+		}
+
+		title += character;
+		index += 1;
+	}
+
+	return invalidMetadata(
+		'Code title is missing its closing double quote.',
+		'Close the title, for example title="src/config.js".',
+	);
+};
+
+const parseHighlightedLines = (selector, lineCount) => {
+	const match = selector.match(lineSelectorPattern);
+	if (!match) {
+		return invalidMetadata(
+			`Invalid code line selector "${selector}".`,
+			'Use positive line numbers and inclusive ranges without spaces, for example {2,4-6}.',
+		);
+	}
+
+	const highlightedLines = new Set();
+	for (const part of match[1].split(',')) {
+		const [startSource, endSource = startSource] = part.split('-');
+		const start = Number.parseInt(startSource, 10);
+		const end = Number.parseInt(endSource, 10);
+
+		if (start < 1 || end < start) {
+			return invalidMetadata(
+				`Invalid code line range "${part}".`,
+				'Use positive line numbers with the lower number first, for example {2,4-6}.',
+			);
+		}
+		if (Number.isInteger(lineCount) && end > lineCount) {
+			return invalidMetadata(
+				`Code line selector "${part}" refers to line ${end}, but the block has ${lineCount} ${lineCount === 1 ? 'line' : 'lines'}.`,
+				`Select only lines 1-${lineCount}.`,
+			);
+		}
+
+		for (let line = start; line <= end; line += 1) {
+			if (highlightedLines.has(line)) {
+				return invalidMetadata(
+					`Code line ${line} is selected more than once.`,
+					'Remove overlapping or repeated line numbers from the selector.',
+				);
+			}
+			highlightedLines.add(line);
+		}
+	}
+
+	return { highlightedLines: [...highlightedLines].sort((left, right) => left - right) };
+};
+
+export const parseCodeFenceMetadata = (rawMetadata, options = {}) => {
+	const source = String(rawMetadata ?? '').trim();
+	if (!source) return { highlightedLines: [], title: null };
+
+	let rest = source;
+	let title = null;
+	if (rest.startsWith(titlePrefix)) {
+		const titleResult = parseTitle(rest);
+		if (titleResult.error) return titleResult;
+		if (!titleResult.title.trim()) {
+			return invalidMetadata(
+				'Code title cannot be empty.',
+				'Remove title="" or provide a short filename or label.',
+			);
+		}
+		title = titleResult.title;
+		rest = titleResult.rest;
+		if (rest && !rest.startsWith(' ')) {
+			return invalidMetadata(
+				'Code title must be separated from the line selector by one space.',
+				'Write metadata as title="src/config.js" {2,4-6}.',
+			);
+		}
+		rest = rest.trim();
+	}
+
+	if (!rest) return { highlightedLines: [], title };
+	if (!rest.startsWith('{')) {
+		return invalidMetadata(
+			`Unknown code fence metadata "${rest}".`,
+			'Use an optional title followed by an optional line selector: title="src/config.js" {2,4-6}.',
+		);
+	}
+	if (/^\{[^}]*\}\s+/.test(rest)) {
+		return invalidMetadata(
+			'The code line selector must come after the optional title.',
+			'Write metadata as title="src/config.js" {2,4-6}.',
+		);
+	}
+
+	const linesResult = parseHighlightedLines(rest, options.lineCount);
+	if (linesResult.error) return linesResult;
+	return {
+		highlightedLines: linesResult.highlightedLines,
+		title,
+	};
+};
+
+const formatDiagnostic = ({ error, label, line, offset }) => ({
+	...error,
+	line,
+	message: `${label} line ${line}: ${error.message}`,
+	offset,
+});
+
+export const getCodeFenceMetadataDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const label = options.label ?? 'Markdown';
+	const lineOffset = options.lineOffset ?? 0;
+	const excludedLanguages = options.excludedLanguages ?? new Set();
+
+	const visit = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === 'code' && !excludedLanguages.has(node.lang)) {
+			const metadataWithoutLanguage = typeof node.lang === 'string'
+				&& (node.lang.startsWith('title=') || node.lang.startsWith('{'));
+			const result = metadataWithoutLanguage
+				? invalidMetadata(
+					'Code fence metadata requires a language before it.',
+					'Add a language first, for example ```js title="src/config.js" {2}.',
+				)
+				: parseCodeFenceMetadata(node.meta, {
+				lineCount: String(node.value ?? '').split('\n').length,
+				});
+			if (result.error) {
+				const line = lineOffset + (node.position?.start.line ?? 1);
+				diagnostics.push(formatDiagnostic({
+					error: result.error,
+					label,
+					line,
+					offset: node.position?.start.offset ?? 0,
+				}));
+			}
+		}
+
+		for (const child of node.children ?? []) visit(child);
+	};
+
+	visit(tree);
+	return diagnostics;
+};
+
+const getTransformerMetadata = (context) => {
+	if (!context.meta.nornaCodeFence) {
+		const result = parseCodeFenceMetadata(context.options.meta?.__raw, {
+			lineCount: context.tokens?.length,
+		});
+		if (result.error) throw new Error(`${result.error.message} ${result.error.fix}`);
+		context.meta.nornaCodeFence = result;
+	}
+	return context.meta.nornaCodeFence;
+};
+
+export const nornaCodeFenceTransformer = {
+	name: 'norna-code-fence-metadata',
+	line(node, line) {
+		const metadata = getTransformerMetadata(this);
+		if (!metadata.highlightedLines.includes(line)) return;
+		this.addClassToHast(node, 'norna-code-line-highlighted');
+		node.properties.dataLine = String(line);
+	},
+	pre(node) {
+		const metadata = getTransformerMetadata(this);
+		if (metadata.highlightedLines.length > 0) {
+			this.addClassToHast(node, 'norna-code-has-highlighted-lines');
+		}
+		if (!metadata.title) return;
+
+		return {
+			type: 'element',
+			tagName: 'figure',
+			properties: { className: ['norna-code-example'] },
+			children: [
+				{
+					type: 'element',
+					tagName: 'figcaption',
+					properties: { className: ['norna-code-title'] },
+					children: [{ type: 'text', value: metadata.title }],
+				},
+				node,
+			],
+		};
+	},
+};

package/scripts/lib/edit-source-link.mjs

@@ -0,0 +1,49 @@
+const assertHttpUrl = (value, label) => {
+	if (typeof value !== 'string' || value.trim() === '') {
+		throw new Error(`${label} must be a non-empty absolute URL.`);
+	}
+
+	let url;
+	try {
+		url = new URL(value.trim());
+	} catch {
+		throw new Error(`${label} must be an absolute URL such as "https://github.com/owner/repository/edit/main/".`);
+	}
+
+	if (!['http:', 'https:'].includes(url.protocol)) {
+		throw new Error(`${label} must use http or https.`);
+	}
+	if (url.username || url.password) {
+		throw new Error(`${label} must not contain credentials.`);
+	}
+	if (url.search || url.hash) {
+		throw new Error(`${label} must not contain a query string or fragment.`);
+	}
+
+	return url;
+};
+
+export const normalizeEditLinkBaseUrl = (value, label = 'editLink.baseUrl') => {
+	const url = assertHttpUrl(value, label);
+	if (!url.pathname.endsWith('/')) url.pathname = `${url.pathname}/`;
+	return url.href;
+};
+
+export const getEditSourceUrl = ({ baseUrl, sourcePath }) => {
+	const normalizedBaseUrl = normalizeEditLinkBaseUrl(baseUrl);
+	if (typeof sourcePath !== 'string' || sourcePath.trim() === '') {
+		throw new Error('Edit-source path must be a non-empty project-relative path.');
+	}
+
+	const normalizedSourcePath = sourcePath.trim().replaceAll('\\', '/');
+	const segments = normalizedSourcePath.split('/');
+	if (
+		normalizedSourcePath.startsWith('/')
+		|| segments.some((segment) => segment === '' || segment === '.' || segment === '..')
+	) {
+		throw new Error(`Edit-source path "${sourcePath}" must be a project-relative path without traversal segments.`);
+	}
+
+	const encodedPath = segments.map((segment) => encodeURIComponent(segment)).join('/');
+	return new URL(encodedPath, normalizedBaseUrl).href;
+};

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

@@ -6,7 +6,11 @@ import {
 	nornaMarkdownBlockDefinitions,
 } from './norna-markdown-blocks.mjs';
 import { resolveNavigationModel } from './navigation-model.mjs';
-import { inspectPublicAssetFilenames, logoAssetFilenames } from './public-asset-conventions.mjs';
+import {
+	inspectPublicAssetFilenames,
+	logoAssetFilenames,
+	socialImageAssetFilenames,
+} from './public-asset-conventions.mjs';
 import { parsePageMarkdownSource } from './page-markdown.mjs';
 import { siteSchema } from './schema-definitions.mjs';
 import { homePageDirectory } from './site-conventions.mjs';
@@ -217,6 +221,18 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 			});
 		}
 	}
+	if (inspection.socialImages.length > 1) {
+		const message = `Multiple social sharing images were found: ${inspection.socialImages.join(', ')}. Keep exactly one of ${socialImageAssetFilenames.join(', ')} in site/public.`;
+		for (const filename of inspection.socialImages) {
+			issues.push({
+				absolutePath: path.join(publicDirectory, filename),
+				code: 'multiple-social-image-files',
+				filename,
+				message,
+				severity: 'error',
+			});
+		}
+	}
 	if (inspection.logos.length === 0 && sitewideLogo?.logoConfigured) {
 		const publicLabel = toPosixPath(path.relative(path.dirname(siteRoot), publicDirectory));
 		issues.push({
@@ -464,7 +480,7 @@ export const getImageCompletionContext = async ({ documentPath, source, line })
 	const page = getPageContext(siteRoot, documentPath);
 	if (!page) return null;
 	const fence = getOpenMarkdownFenceAtLine(source, line);
-	if (!fence || !['norna-image-stack', 'norna-image-carousel', 'norna-card-list'].includes(fence.type)) return null;
+	if (!fence || !['image-stack', 'image-carousel', 'card-list'].includes(fence.type)) return null;
 
 	const currentLine = source.replace(/\r\n?/g, '\n').split('\n')[line] ?? '';
 	if (!/^\s*(?:-\s+)?image:\s*[^\s]*$/.test(currentLine)) return null;
@@ -563,7 +579,7 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 			code: 'local-markdown-image',
 			severity: 'warning',
 			line: reference.line,
-			message: `Local Markdown image "${reference.target}" is not managed by Norna. Use norna-image-stack, norna-image-carousel, or norna-card-list for validated and synchronized site images.`,
+			message: `Local Markdown image "${reference.target}" is not managed by Norna. Use image-stack, image-carousel, or card-list for validated and synchronized site images.`,
 		});
 	}
 
@@ -619,16 +635,20 @@ export const getMarkdownDiagnostics = async ({ documentPath, source }) => {
 };
 
 export const nornaBlockDefinitions = Object.freeze({
-	'norna-image-stack': Object.freeze({
-		...nornaMarkdownBlockDefinitions['norna-image-stack'],
-		snippet: '```norna-image-stack\n- image: ${1:filename.jpg}\n  alt: ${2:Alternative text}\n  caption: ${3:Caption}\n```',
+	'image-stack': Object.freeze({
+		...nornaMarkdownBlockDefinitions['image-stack'],
+		snippet: '```image-stack\n- image: ${1:filename.jpg}\n  alt: ${2:Alternative text}\n  caption: ${3:Caption}\n```',
+	}),
+	'image-carousel': Object.freeze({
+		...nornaMarkdownBlockDefinitions['image-carousel'],
+		snippet: '```image-carousel\n- image: ${1:first.jpg}\n  alt: ${2:Alternative text}\n- image: ${3:second.jpg}\n  alt: ${4:Alternative text}\n```',
 	}),
-	'norna-image-carousel': Object.freeze({
-		...nornaMarkdownBlockDefinitions['norna-image-carousel'],
-		snippet: '```norna-image-carousel\n- image: ${1:first.jpg}\n  alt: ${2:Alternative text}\n- image: ${3:second.jpg}\n  alt: ${4:Alternative text}\n```',
+	'card-list': Object.freeze({
+		...nornaMarkdownBlockDefinitions['card-list'],
+		snippet: '```card-list\nlayout: ${1|image-top,image-left,image-right|}\nflow: ${2|grid,stack|}\nsize: ${3|s,m,l,xl|}\n\n- title: ${4:Card title}\n  text: ${5:Card text}\n  image: ${6:filename.jpg}\n```',
 	}),
-	'norna-card-list': Object.freeze({
-		...nornaMarkdownBlockDefinitions['norna-card-list'],
-		snippet: '```norna-card-list\nlayout: ${1|image-top,image-left,image-right|}\nflow: ${2|grid,stack|}\nsize: ${3|s,m,l,xl|}\n\n- title: ${4:Card title}\n  text: ${5:Card text}\n  image: ${6:filename.jpg}\n```',
+	'page-list': Object.freeze({
+		...nornaMarkdownBlockDefinitions['page-list'],
+		snippet: '```page-list\n```',
 	}),
 });

package/scripts/lib/image-presentation.mjs

@@ -1,2 +1,6 @@
 export const imagePresentationNames = Object.freeze(['prose-aligned', 'centered-fit']);
 export const defaultImagePresentation = 'prose-aligned';
+export const defaultImageMaxAvailableHeightPercent = Object.freeze({
+	desktop: 74,
+	mobile: 68,
+});

package/scripts/lib/navigation-model.mjs

@@ -19,31 +19,27 @@ const getNodeDepth = (node) => node.depth ?? 1;
 
 const getTopLevelPagePath = (pagePath) => pagePath?.split('/')[0] ?? '';
 
-const branchNeedsPageRail = (nodes, pagePath) => {
-	const rootPath = getTopLevelPagePath(pagePath);
-	if (!rootPath) return false;
+const getActiveBranchNodes = (nodes, currentPage) => {
+	if (!currentPage) return [];
+	if (currentPage.isHome) return nodes.filter((node) => node.isHome);
 
-	return nodes.some((node) => (
-		(node.pagePath === rootPath && node.kind === 'category')
+	const rootPath = getTopLevelPagePath(currentPage.pagePath);
+	return nodes.filter((node) => (
+		node.pagePath === rootPath
 		|| node.pagePath?.startsWith(`${rootPath}/`)
 	));
 };
 
-export const getAutomaticNavigationMode = (nodes, currentPage = null) => {
+export const getAutomaticNavigationMode = (nodes) => {
 	const listedNodes = getListedNodes(nodes);
 	if (listedNodes.length <= 1) return 'sections';
 
-	if (currentPage) {
-		if (currentPage.isHome) return 'top';
-		return branchNeedsPageRail(listedNodes, currentPage.pagePath) ? 'tree' : 'top';
-	}
-
 	return listedNodes.some((node) => node.kind === 'category' || getNodeDepth(node) > 1)
 		? 'tree'
 		: 'top';
 };
 
-export const resolveNavigationModel = ({ mode = 'automatic', nodes, currentPage = null }) => {
+export const resolveNavigationModel = ({ mode = 'automatic', nodes }) => {
 	const requestedMode = assertNavigationMode(mode);
 	const listedNodes = getListedNodes(nodes);
 	const hasCategories = listedNodes.some((node) => node.kind === 'category');
@@ -57,7 +53,7 @@ export const resolveNavigationModel = ({ mode = 'automatic', nodes, currentPage
 
 	return Object.freeze({
 		mode: requestedMode === 'automatic'
-			? getAutomaticNavigationMode(listedNodes, currentPage)
+			? getAutomaticNavigationMode(listedNodes)
 			: requestedMode,
 		requestedMode,
 		listedNodeCount: listedNodes.length,
@@ -66,3 +62,28 @@ export const resolveNavigationModel = ({ mode = 'automatic', nodes, currentPage
 		maximumDepth,
 	});
 };
+
+export const resolvePageContentsPlacement = ({
+	navigationMode,
+	nodes,
+	currentPage,
+	headingCount,
+}) => {
+	const listedNodes = getListedNodes(nodes);
+	const activeBranchNodes = getActiveBranchNodes(listedNodes, currentPage);
+	const activeBranchDepth = activeBranchNodes.reduce((maximum, node) => (
+		Math.max(maximum, getNodeDepth(node))
+	), 0);
+	const hasPageContents = headingCount >= 2;
+	const placement = navigationMode !== 'tree' || !hasPageContents
+		? 'none'
+		: activeBranchDepth <= 2
+			? 'page-tree'
+			: 'contents-rail';
+
+	return Object.freeze({
+		activeBranchDepth,
+		hasPageContents,
+		placement,
+	});
+};