@janga/norna 0.7.22 → 0.7.24

package/scripts/lib/site-link-graph.mjs

@@ -0,0 +1,357 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+	createPageAliasModel,
+	generatedSiteRoutes,
+} from './page-aliases.mjs';
+import { parsePageMarkdownSource } from './page-markdown.mjs';
+import {
+	parseContentFrontmatter,
+	splitSiteFile,
+	toPosixPath,
+} from './site-content.mjs';
+import {
+	sitePagesLabel,
+	sitePublicDir,
+	sitePublicLabel,
+} from './site-paths.mjs';
+import { getSiteNodePathname } from './site-page-urls.mjs';
+import { getSiteStructure } from './site-structure.mjs';
+
+const internalUrlOrigin = 'https://norna.invalid';
+const externalSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
+
+const readPublicFiles = async (directory, relativeDirectory = '') => {
+	const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+		if (error?.code === 'ENOENT') return [];
+		throw error;
+	});
+	const files = [];
+
+	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+		const relativePath = relativeDirectory
+			? path.join(relativeDirectory, entry.name)
+			: entry.name;
+		const entryPath = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await readPublicFiles(entryPath, relativePath));
+		} else if (entry.isFile()) {
+			files.push({
+				filePath: entryPath,
+				label: `${sitePublicLabel}/${toPosixPath(relativePath)}`,
+				pathname: `/${toPosixPath(relativePath)}`,
+			});
+		}
+	}
+
+	return files;
+};
+
+const decodePathname = (pathname) => {
+	const decodedSegments = pathname.split('/').map((segment) => decodeURIComponent(segment));
+	if (decodedSegments.some((segment) => segment.includes('/') || segment.includes('\\') || segment.includes('\0'))) {
+		throw new Error('Encoded slashes, backslashes, and null bytes are not valid internal paths.');
+	}
+	return decodedSegments.join('/');
+};
+
+const decodeFragment = (fragment) => decodeURIComponent(fragment);
+
+const getPageLookupPathname = (pathname) => {
+	if (pathname === '/' || pathname === '/index.html') return '/';
+	if (pathname.endsWith('/index.html')) return pathname.slice(0, -'index.html'.length);
+	if (pathname.endsWith('/')) return pathname;
+	const finalSegment = pathname.split('/').at(-1) ?? '';
+	return finalSegment.includes('.') ? null : `${pathname}/`;
+};
+
+const isExternalTarget = (target) => target.startsWith('//') || externalSchemePattern.test(target);
+
+export const resolveInternalTarget = (target, sourcePathname) => {
+	if (isExternalTarget(target)) return { kind: 'external' };
+
+	let url;
+	try {
+		url = new URL(target, `${internalUrlOrigin}${sourcePathname}`);
+	} catch {
+		return {
+			kind: 'invalid',
+			reason: 'The target is not a valid relative or site-relative URL.',
+		};
+	}
+
+	if (url.origin !== internalUrlOrigin) return { kind: 'external' };
+
+	try {
+		const pathname = decodePathname(url.pathname);
+		const fragment = url.hash.length > 1 ? decodeFragment(url.hash.slice(1)) : '';
+		return {
+			kind: 'internal',
+			fragment,
+			pageLookupPathname: getPageLookupPathname(pathname),
+			pathname,
+			query: url.search,
+		};
+	} catch (error) {
+		return {
+			kind: 'invalid',
+			reason: error instanceof Error ? error.message : String(error),
+		};
+	}
+};
+
+const createPageRecord = ({ contentFile, data = {}, document }) => {
+	const pathname = getSiteNodePathname(contentFile);
+	const anchors = new Map([['page-title', {
+		id: 'page-title',
+		line: document.pageTitle?.line ?? 1,
+		title: document.pageTitle?.title ?? 'Page title',
+	}]]);
+
+	for (const heading of document.headings) {
+		if ((heading.depth !== 2 && heading.depth !== 3) || !heading.id || anchors.has(heading.id)) continue;
+		anchors.set(heading.id, heading);
+	}
+
+	return {
+		aliases: data.page?.aliases ?? [],
+		anchors,
+		contentFile,
+		document,
+		navigation: {
+			listed: data.navigation?.listed ?? true,
+		},
+		pathname,
+		title: document.pageTitle?.title ?? contentFile.pageId,
+	};
+};
+
+const createIssue = (reference, code, message, fix) => ({
+	code,
+	fix,
+	message,
+	reference,
+	severity: 'error',
+});
+
+const getTargetKey = ({ fragment, pageLookupPathname, pathname }) => {
+	const identityPathname = pageLookupPathname ?? pathname;
+	return `${identityPathname}${fragment ? `#${fragment}` : ''}`;
+};
+
+const looksLikePublicFile = (pathname) => {
+	if (pathname.endsWith('/')) return false;
+	return (pathname.split('/').at(-1) ?? '').includes('.');
+};
+
+export const createSiteLinkGraph = ({
+	siteStructure,
+	pageDocuments,
+	publicFiles = [],
+	generatedRoutes,
+}) => {
+	const activeGeneratedRoutes = generatedRoutes ?? generatedSiteRoutes;
+	const documentsByDirectory = new Map(pageDocuments.map(({ contentFile, data, document }) => [
+		contentFile.pageDirectory,
+		{ contentFile, data, document },
+	]));
+	const pages = siteStructure.contentFiles.map((contentFile) => {
+		const pageDocument = documentsByDirectory.get(contentFile.pageDirectory);
+		if (!pageDocument) throw new Error(`No parsed Markdown document was provided for ${contentFile.contentLabel}.`);
+		return createPageRecord(pageDocument);
+	});
+	const pagesByPathname = new Map(pages.map((page) => [page.pathname, page]));
+	const categoriesByPathname = new Map(siteStructure.categories.map((category) => [
+		getSiteNodePathname(category),
+		{ ...category, pathname: getSiteNodePathname(category) },
+	]));
+	const publicFilesByPathname = new Map();
+	for (const file of publicFiles) {
+		publicFilesByPathname.set(file.pathname, file);
+		if (file.pathname === '/index.html') publicFilesByPathname.set('/', file);
+		if (file.pathname.endsWith('/index.html')) {
+			publicFilesByPathname.set(file.pathname.slice(0, -'index.html'.length), file);
+		}
+	}
+	const aliasModel = createPageAliasModel({
+		categories: siteStructure.categories,
+		pages,
+		publicFiles,
+		generatedRoutes: activeGeneratedRoutes,
+	});
+	const generatedRoutesByPathname = new Map(
+		activeGeneratedRoutes.map((route) => [route.pathname, route]),
+	);
+
+	const references = [];
+	const referencesByTarget = new Map();
+	const diagnostics = [...aliasModel.diagnostics];
+
+	for (const page of pages) {
+		for (const sourceReference of page.document.links) {
+			const target = resolveInternalTarget(sourceReference.target, page.pathname);
+			if (target.kind === 'external') continue;
+
+			const reference = {
+				...sourceReference,
+				sourceContentFile: page.contentFile,
+				sourcePage: page,
+				target,
+			};
+			references.push(reference);
+
+			if (target.kind === 'invalid') {
+				diagnostics.push(createIssue(
+					reference,
+					'invalid-internal-url',
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} is invalid. ${target.reason}`,
+					'Use a valid fragment, relative URL, site-relative URL, or external URL.',
+				));
+				continue;
+			}
+
+			const targetKey = getTargetKey(target);
+			if (!referencesByTarget.has(targetKey)) referencesByTarget.set(targetKey, []);
+			referencesByTarget.get(targetKey).push(reference);
+
+			const targetPage = target.pageLookupPathname
+				? pagesByPathname.get(target.pageLookupPathname)
+				: null;
+			if (targetPage) {
+				reference.resolution = { kind: 'page', page: targetPage, pathname: targetPage.pathname };
+				if (target.fragment && !targetPage.anchors.has(target.fragment)) {
+					const availableAnchors = Array.from(targetPage.anchors.keys());
+					const displayedAnchors = availableAnchors.slice(0, 8).map((anchor) => `#${anchor}`);
+					const omittedCount = availableAnchors.length - displayedAnchors.length;
+					diagnostics.push(createIssue(
+						reference,
+						'missing-internal-anchor',
+						`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to missing heading anchor "#${target.fragment}" on ${targetPage.pathname}.`,
+						availableAnchors.length > 0
+							? `Use an existing anchor: ${displayedAnchors.join(', ')}${omittedCount > 0 ? `, and ${omittedCount} more` : ''}.`
+							: 'Add the intended H2 or H3 heading, or remove the fragment from the link.',
+					));
+				}
+				continue;
+			}
+
+			const targetAlias = target.pageLookupPathname
+				? aliasModel.aliasesByPathname.get(target.pageLookupPathname)
+				: null;
+			if (targetAlias) {
+				const aliasTargetPage = pagesByPathname.get(targetAlias.targetPathname);
+				if (!aliasTargetPage) {
+					throw new Error(`Page alias "${targetAlias.pathname}" has no target page ${targetAlias.targetPathname}.`);
+				}
+				reference.resolution = {
+					alias: targetAlias,
+					kind: 'page-alias',
+					page: aliasTargetPage,
+					pathname: aliasTargetPage.pathname,
+				};
+				if (target.fragment && !aliasTargetPage.anchors.has(target.fragment)) {
+					const availableAnchors = Array.from(aliasTargetPage.anchors.keys());
+					diagnostics.push(createIssue(
+						reference,
+						'missing-internal-anchor',
+						`Internal link "${sourceReference.target}" on line ${sourceReference.line} points through alias ${targetAlias.pathname} to missing heading anchor "#${target.fragment}" on ${aliasTargetPage.pathname}.`,
+						availableAnchors.length > 0
+							? `Use an existing anchor: ${availableAnchors.slice(0, 8).map((anchor) => `#${anchor}`).join(', ')}.`
+							: 'Add the intended H2 or H3 heading, or remove the fragment from the link.',
+					));
+				}
+				continue;
+			}
+
+			const generatedRoute = generatedRoutesByPathname.get(
+				target.pageLookupPathname ?? target.pathname,
+			);
+			if (generatedRoute && !target.fragment) {
+				reference.resolution = {
+					kind: 'generated-route',
+					pathname: generatedRoute.pathname,
+					route: generatedRoute,
+				};
+				continue;
+			}
+
+			const targetCategory = target.pageLookupPathname
+				? categoriesByPathname.get(target.pageLookupPathname)
+				: null;
+			if (targetCategory) {
+				reference.resolution = { category: targetCategory, kind: 'category', pathname: targetCategory.pathname };
+				diagnostics.push(createIssue(
+					reference,
+					'category-has-no-url',
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to navigation category ${targetCategory.pathname}, which does not have its own page.`,
+					'Link to one of the category pages, or replace category.yaml with content.md when the collection needs its own page.',
+				));
+				continue;
+			}
+
+			const publicFile = publicFilesByPathname.get(target.pathname);
+			if (publicFile) {
+				reference.resolution = { file: publicFile, kind: 'public-file', pathname: target.pathname };
+				continue;
+			}
+
+			if (looksLikePublicFile(target.pathname)) {
+				reference.resolution = { kind: 'missing-public-file', pathname: target.pathname };
+				diagnostics.push(createIssue(
+					reference,
+					'missing-public-file',
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to public file "${target.pathname}", but no matching file exists under ${sitePublicLabel}/.`,
+					`Add the file under ${sitePublicLabel}/ with the same relative path, or correct the link.`,
+				));
+				continue;
+			}
+
+			const missingPathname = target.pageLookupPathname ?? target.pathname;
+			reference.resolution = { kind: 'missing-page', pathname: missingPathname };
+			diagnostics.push(createIssue(
+				reference,
+				'missing-internal-page',
+				`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to page "${missingPathname}", but that page does not exist.`,
+				`Correct the link or create the page at the intended position under ${sitePagesLabel}/.`,
+			));
+		}
+	}
+
+	return {
+		aliasModel,
+		aliases: aliasModel.aliases,
+		aliasesByPathname: aliasModel.aliasesByPathname,
+		categoriesByPathname,
+		diagnostics,
+		pages,
+		pagesByPathname,
+		publicFilesByPathname,
+		references,
+		referencesByTarget,
+	};
+};
+
+export const getSiteLinkGraph = async (options = {}) => {
+	const siteStructure = options.siteStructure ?? await getSiteStructure();
+	const [pageDocuments, publicFiles] = await Promise.all([
+		Promise.all(siteStructure.contentFiles.map(async (contentFile) => {
+			const source = await readFile(contentFile.contentPath, 'utf8');
+			const { frontmatterBody } = splitSiteFile(source, contentFile.contentLabel);
+			return {
+				contentFile,
+				data: parseContentFrontmatter(frontmatterBody, contentFile.contentLabel),
+				document: await parsePageMarkdownSource(source, { label: contentFile.contentLabel }),
+			};
+		})),
+		readPublicFiles(options.publicDir ?? sitePublicDir),
+	]);
+
+	return createSiteLinkGraph({
+		pageDocuments,
+		publicFiles,
+		siteStructure,
+		generatedRoutes: options.generatedRoutes,
+	});
+};
+
+export const getSitePublicFiles = async (publicDir = sitePublicDir) => readPublicFiles(publicDir);

package/scripts/lib/site-navigation-tree.mjs

@@ -0,0 +1,85 @@
+export const getSiteNavigationTree = (entries) => {
+	const nodes = new Map();
+	const roots = [];
+
+	for (const entry of entries) {
+		nodes.set(entry.node.pagePath, { ...entry, children: [] });
+	}
+
+	for (const entry of entries) {
+		const node = nodes.get(entry.node.pagePath);
+		if (!node) continue;
+
+		if (entry.node.isHome || entry.node.parentPagePath === null) {
+			roots.push(node);
+			continue;
+		}
+
+		const parent = nodes.get(entry.node.parentPagePath);
+		if (!parent) {
+			throw new Error(`Site node "${entry.node.pagePath}" has no parent node "${entry.node.parentPagePath}".`);
+		}
+
+		parent.children.push(node);
+	}
+
+	return roots;
+};
+
+export const getListedSiteNavigationTree = (entries) => {
+	const filterListed = (nodes) => nodes.flatMap((node) => {
+		if (!node.node.isHome && !node.node.navigation.listed) return [];
+		const children = filterListed(node.children);
+		if (node.node.kind === 'category' && children.length === 0) return [];
+		return [{ ...node, children }];
+	});
+
+	return filterListed(getSiteNavigationTree(entries));
+};
+
+export const getFirstPageInNavigationNode = (node) => {
+	if (node.node.kind === 'page') return node.node;
+
+	for (const child of node.children) {
+		const page = getFirstPageInNavigationNode(child);
+		if (page) return page;
+	}
+
+	return null;
+};
+
+export const flattenSiteNavigationTree = (nodes) => nodes.flatMap((node) => [
+	node,
+	...flattenSiteNavigationTree(node.children),
+]);
+
+export const getSequentialPageNavigation = (nodes, currentPagePath) => {
+	const activeRoot = nodes.find((root) => (
+		flattenSiteNavigationTree([root]).some(({ node }) => node.pagePath === currentPagePath)
+	));
+	if (!activeRoot) return { previous: null, next: null };
+
+	const pages = flattenSiteNavigationTree([activeRoot])
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+	const currentIndex = pages.findIndex(({ pagePath }) => pagePath === currentPagePath);
+	if (currentIndex < 0) return { previous: null, next: null };
+
+	return {
+		previous: pages[currentIndex - 1] ?? null,
+		next: pages[currentIndex + 1] ?? null,
+	};
+};
+
+export const getDirectChildPages = (nodes, currentPagePath) => {
+	const current = flattenSiteNavigationTree(nodes)
+		.find(({ node }) => node.pagePath === currentPagePath);
+	if (!current) return [];
+	const children = current.node.isHome
+		? nodes.filter(({ node }) => !node.isHome)
+		: current.children;
+
+	return children
+		.filter(({ node }) => node.kind === 'page')
+		.map(({ node }) => node);
+};

package/scripts/lib/site-page-urls.mjs

@@ -0,0 +1,10 @@
+export const getSiteNodePathname = (node) => node.isHome || !node.pagePath
+	? '/'
+	: `/${node.pagePath}/`;
+
+export const getAbsolutePageUrl = (siteUrl, pathname) => {
+	const baseUrl = new URL(siteUrl);
+	if (!baseUrl.pathname.endsWith('/')) baseUrl.pathname = `${baseUrl.pathname}/`;
+
+	return new URL(pathname === '/' ? '' : pathname.replace(/^\//, ''), baseUrl).href;
+};

package/scripts/lib/sitemap.mjs

@@ -0,0 +1,34 @@
+import { getAbsolutePageUrl, getSiteNodePathname } from './site-page-urls.mjs';
+
+export const sitemapFilename = 'sitemap.xml';
+
+const escapeXml = (value) => String(value)
+	.replaceAll('&', '&')
+	.replaceAll('<', '&lt;')
+	.replaceAll('>', '&gt;')
+	.replaceAll('"', '&quot;')
+	.replaceAll("'", '&apos;');
+
+const compareStrings = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+
+export const getSitemapUrls = ({ siteStructure, siteUrl }) => (
+	siteStructure.contentFiles
+		.map((page) => getSiteNodePathname(page))
+		.sort(compareStrings)
+		.map((pathname) => getAbsolutePageUrl(siteUrl, pathname))
+);
+
+export const createSitemapXml = (options) => {
+	const urls = getSitemapUrls(options);
+	const lines = [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+	];
+
+	for (const url of urls) {
+		lines.push('  <url>', `    <loc>${escapeXml(url)}</loc>`, '  </url>');
+	}
+
+	lines.push('</urlset>');
+	return `${lines.join('\n')}\n`;
+};

package/scripts/lib/social-image-assets.mjs

@@ -0,0 +1,30 @@
+import { getPublicAssetInspection } from './logo-assets.mjs';
+import {
+	socialImageAssetDefinitions,
+	socialImageAssetFilenames,
+} from './public-asset-conventions.mjs';
+import { sitePublicLabel } from './site-paths.mjs';
+
+const definitionsByFilename = new Map(
+	socialImageAssetDefinitions.map((definition) => [definition.filename, definition]),
+);
+
+export const getSocialImageAssets = () => getPublicAssetInspection().socialImages
+	.map((filename) => ({
+		...definitionsByFilename.get(filename),
+		filename,
+		href: `/${filename}`,
+	}));
+
+export const getSocialImageAsset = () => {
+	const assets = getSocialImageAssets();
+
+	if (assets.length > 1) {
+		throw new Error([
+			`Found multiple social sharing images in ${sitePublicLabel}. Keep exactly one of ${socialImageAssetFilenames.join(', ')}.`,
+			...assets.map(({ filename }) => `- ${sitePublicLabel}/${filename}`),
+		].join('\n'));
+	}
+
+	return assets[0] ?? null;
+};

package/scripts/lib/theme-presets.mjs

@@ -4,7 +4,7 @@ import { resolveThemeProfileRecipe } from './theme-profiles.mjs';
 
 export const themePresetRecipes = Object.freeze({
 	portfolio: Object.freeze({
-		color: 'near-monochrome-dark',
+		color: 'near-monochrome-adaptive',
 		typography: 'restrained-sans',
 		rhythm: 'balanced',
 		geometry: 'image-led',
@@ -50,25 +50,25 @@ export const themePresetDefinitions = Object.freeze({
 		title: 'Portfolio',
 		description: 'For portfolios and image-led sites, with restrained typography and generous space for images.',
 		recipe: themePresetRecipes.portfolio,
-		readerControls: Object.freeze({ colorMode: true }),
+		readerControls: Object.freeze({ appearance: true }),
 	}),
 	documentation: Object.freeze({
 		title: 'Documentation',
 		description: 'For guides and reference material, with reading-focused typography and compact spacing.',
 		recipe: themePresetRecipes.documentation,
-		readerControls: Object.freeze({ colorMode: true, focusReading: true }),
+		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	project: Object.freeze({
 		title: 'Project',
 		description: 'For project and product sites that balance explanation, code, cards, and images.',
 		recipe: themePresetRecipes.project,
-		readerControls: Object.freeze({ colorMode: true, focusReading: true }),
+		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	statement: Object.freeze({
 		title: 'Statement',
 		description: 'For short, expressive sites, with larger typography, airy spacing, and stronger section emphasis.',
 		recipe: themePresetRecipes.statement,
-		readerControls: Object.freeze({ colorMode: true }),
+		readerControls: Object.freeze({ appearance: true }),
 	}),
 });
 
@@ -115,35 +115,56 @@ export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	const overrides = structuredClone(theme ?? {});
 	delete overrides.preset;
 
-	return {
+	const resolved = {
 		preset: presetName,
 		...mergeDeep(getThemePreset(presetName, sourceLabel), overrides),
 	};
+
+	if (
+		overrides.images?.presentation === 'prose-aligned'
+		&& overrides.images.maxAvailableHeightPercent === undefined
+	) {
+		delete resolved.images.maxAvailableHeightPercent;
+	}
+
+	return resolved;
 };
 
 const mergePageThemePart = (base, override, keys) => Object.fromEntries(keys
 	.filter((key) => override?.[key] !== undefined || base?.[key] !== undefined)
 	.map((key) => [key, override?.[key] ?? base?.[key]]));
 
-export const mergePageThemeConfig = (base = {}, override = {}) => ({
-	...base,
-	layout: {
-		...(base.layout ?? {}),
-		...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
-	},
-	images: {
+export const mergePageThemeConfig = (base = {}, override = {}) => {
+	const images = {
 		...(base.images ?? {}),
 		...mergePageThemePart(base.images, override.images, [
+			'presentation',
 			'width',
 			'maxAvailableWidthPercent',
 			'maxAvailableHeightPercent',
 		]),
-	},
-	sections: {
-		...(base.sections ?? {}),
-		...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
-	},
-});
+	};
+
+	if (
+		override.images?.presentation === 'prose-aligned'
+		&& override.images.maxAvailableHeightPercent === undefined
+	) {
+		delete images.maxAvailableHeightPercent;
+	}
+
+	return {
+		...base,
+		layout: {
+			...(base.layout ?? {}),
+			...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
+		},
+		images,
+		sections: {
+			...(base.sections ?? {}),
+			...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
+		},
+	};
+};
 
 const quote = (value) => JSON.stringify(value);
 const responsiveValueLines = (label, value, indent = 2) => {
@@ -158,7 +179,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { colorMode, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
+	const { appearance, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -169,12 +190,12 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		`preset: ${presetName}`,
 		'',
 		'# Initial appearance. System follows the visitor\'s operating-system preference.',
-		'colorMode:',
-		`  default: ${colorMode.default}`,
+		'appearance:',
+		`  default: ${appearance.default}`,
 		'',
 		'# Optional reader controls shown with the always-available reading-width choice.',
 		'readerControls:',
-		`  colorMode: ${readerControls.colorMode === true}`,
+		`  appearance: ${readerControls.appearance === true}`,
 		`  focusReading: ${readerControls.focusReading === true}`,
 		'',
 		'# Alternatives: square, rounded.',
@@ -194,16 +215,23 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'  # firstSectionTop, headingToBlock, imageGap, and sectionGap.',
 		'',
 		'images:',
+		'  # Alternatives: prose-aligned, centered-fit.',
+		`  presentation: ${images.presentation}`,
 		'  # width accepts a positive CSS length.',
 		`  width: ${images.width}`,
 		'  # Percent values must be greater than 0 and at most 100.',
 		...responsiveValueLines('maxAvailableWidthPercent', images.maxAvailableWidthPercent),
-		...responsiveValueLines('maxAvailableHeightPercent', images.maxAvailableHeightPercent),
+		...(images.maxAvailableHeightPercent
+			? [
+				'  # Viewport-height limits apply only to centered-fit presentation.',
+				...responsiveValueLines('maxAvailableHeightPercent', images.maxAvailableHeightPercent),
+			]
+			: []),
 		'',
 		'blocks:',
 		'  cardList:',
 		'    # Alternatives: text, narrow, normal, wide.',
-		'    # A width written in a norna-card-list block overrides this default.',
+		'    # A width written in a card-list block overrides this default.',
 		`    width: ${blocks.cardList.width}`,
 		'',
 		'typography:',