@janga/norna 0.7.26 → 0.7.28

package/scripts/add-site-node.mjs

@@ -1,26 +1,15 @@
-import { randomUUID } from 'node:crypto';
-import { mkdir, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { dump as dumpYaml } from 'js-yaml';
-import { slugifyAsciiIdentifier } from './lib/heading-ids.mjs';
-import { pageDirectoryPattern } from './lib/page-model.mjs';
-import {
-	invocationRoot,
-	siteDir,
-	sitePagesDir,
-	siteProjectRoot,
-} from './lib/site-paths.mjs';
-import { getSiteStructure } from './lib/site-structure.mjs';
+import { invocationRoot, siteDir, siteProjectRoot } from './lib/site-paths.mjs';
+import { createSiteNode, planSiteNodeCreation } from './lib/site-node-create.mjs';
 
 const usage = `
 Usage:
   norna page:add <title> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
-  norna category:add <label> [--parent <path>] [--slug <slug>] [--order <NNN>] [--dry-run]
 
 Parent selection:
   --parent /                 Add a top-level node
   --parent /guides/         Add a child below the guides node
-  no --parent               Use the current node directory, or site/pages/
+  no --parent               Use the site root, current node directory, or site/pages/
 `.trim();
 
 const parseValueOption = (rawArgs, index, name) => {
@@ -85,38 +74,6 @@ const parseArgs = (rawArgs) => {
 	return options;
 };
 
-const parseOrder = (value) => {
-	if (!/^\d{1,3}$/.test(value)) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	const order = Number.parseInt(value, 10);
-	if (order < 1 || order > 999) {
-		throw new Error(`Invalid --order "${value}". Use an integer from 1 to 999.`);
-	}
-	return order;
-};
-
-const normalizeParentPath = (value) => {
-	if (value === '/') return '';
-	if (value.includes('\\') || value.includes('?') || value.includes('#')) {
-		throw new Error(`Invalid --parent "${value}". Use a logical path such as /guides/installation/.`);
-	}
-	const normalized = value.replace(/^\/+|\/+$/g, '');
-	if (!normalized || normalized.split('/').some((segment) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(segment))) {
-		throw new Error(`Invalid --parent "${value}". Use / for the top level or a logical path such as /guides/installation/.`);
-	}
-	return normalized;
-};
-
-const getNextOrder = (siblings) => {
-	const highestOrder = siblings.reduce((highest, node) => Math.max(highest, node.pageOrder), 0);
-	const nextOrder = Math.floor(highestOrder / 10) * 10 + 10;
-	if (nextOrder > 999) {
-		throw new Error('No automatic page order remains below 1000. Reorder the sibling nodes before adding another one.');
-	}
-	return nextOrder;
-};
-
 const toDisplayPath = (filePath) => {
 	const relativePath = path.relative(siteProjectRoot, filePath);
 	return (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)
@@ -124,85 +81,8 @@ const toDisplayPath = (filePath) => {
 		: filePath).split(path.sep).join('/');
 };
 
-const escapeMarkdownHeading = (value) => value.replace(/([\\`*_[\]{}<>#])/g, '\\$1');
-
-const canonicalDirectory = async (directory) => realpath(directory).catch((error) => {
-	if (error?.code === 'ENOENT') return path.resolve(directory);
-	throw error;
-});
-
-const resolveParent = async ({ nodes, parent }) => {
-	if (parent !== null) {
-		const parentPath = normalizeParentPath(parent);
-		if (!parentPath) {
-			return { collectionDir: sitePagesDir, node: null, pagePath: '' };
-		}
-		const node = nodes.find((candidate) => candidate.pagePath === parentPath);
-		if (!node) {
-			throw new Error(`Cannot find parent "${parent}". Use an existing logical page/category path, or / for the top level.`);
-		}
-		if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
-		return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
-	}
-
-	const currentDirectory = await canonicalDirectory(invocationRoot);
-	if (currentDirectory === await canonicalDirectory(sitePagesDir)) {
-		return { collectionDir: sitePagesDir, node: null, pagePath: '' };
-	}
-	let node = null;
-	for (const candidate of nodes) {
-		if (await canonicalDirectory(candidate.nodeDir) === currentDirectory) {
-			node = candidate;
-			break;
-		}
-	}
-	if (!node) {
-		throw new Error([
-			'Cannot infer where to add the node from the current directory.',
-			`Run the command from ${toDisplayPath(sitePagesDir)} for a top-level node, from an existing page/category directory for a child, or pass --parent.`,
-		].join('\n'));
-	}
-	if (node.isHome) throw new Error('The homepage cannot contain child pages or categories.');
-	return { collectionDir: path.join(node.nodeDir, 'pages'), node, pagePath: node.pagePath };
-};
-
-const assertCollectionDirectory = async (collectionDir) => {
-	try {
-		const info = await stat(collectionDir);
-		if (!info.isDirectory()) throw new Error(`${toDisplayPath(collectionDir)} exists but is not a directory.`);
-		return false;
-	} catch (error) {
-		if (error?.code !== 'ENOENT') throw error;
-		await mkdir(collectionDir);
-		return true;
-	}
-};
-
-const writeNode = async ({ destination, kind, title }) => {
-	const stagingRoot = path.join(siteDir, '.norna', 'create');
-	await mkdir(stagingRoot, { recursive: true });
-	const stagingDirectory = path.join(stagingRoot, `node-${process.pid}-${randomUUID()}`);
-	await mkdir(stagingDirectory);
-
-	try {
-		if (kind === 'page') {
-			await writeFile(path.join(stagingDirectory, 'content.md'), `# ${escapeMarkdownHeading(title)}\n\n## Introduction\n\nStart writing here.\n`);
-			await mkdir(path.join(stagingDirectory, 'images'));
-		} else {
-			await writeFile(path.join(stagingDirectory, 'category.yaml'), dumpYaml({ label: title }, {
-				lineWidth: -1,
-				noRefs: true,
-			}));
-			await mkdir(path.join(stagingDirectory, 'pages'));
-		}
-		await rename(stagingDirectory, destination);
-	} finally {
-		await rm(stagingDirectory, { force: true, recursive: true });
-	}
-};
-
 const [kind, ...rawArgs] = process.argv.slice(2);
-if (!['category', 'page'].includes(kind)) throw new Error(usage);
+if (kind !== 'page') throw new Error(usage);
 const options = parseArgs(rawArgs);
 if (options.help) {
 	console.log(usage);
@@ -210,42 +90,14 @@ if (options.help) {
 }
 
 const title = options.titleParts.join(' ').trim();
-if (!title || /[\r\n]/.test(title)) throw new Error(`A one-line ${kind === 'page' ? 'page title' : 'category label'} is required.\n${usage}`);
-const slug = options.slug ?? slugifyAsciiIdentifier(title);
-if (!slug || !pageDirectoryPattern.test(`010-${slug}`)) {
-	throw new Error(`Invalid ${options.slug === null ? 'generated ' : ''}slug "${slug}". Use lowercase ASCII letters, numbers, and single hyphens; pass --slug when automatic transliteration is unsuitable.`);
-}
-
-const structure = await getSiteStructure();
-const parent = await resolveParent({ nodes: structure.nodes, parent: options.parent });
-const siblings = structure.nodes.filter((node) => node.parentPagePath === (parent.pagePath || null) && !node.isHome);
-if (siblings.some((node) => node.pageId === slug)) {
-	throw new Error(`Cannot create "${slug}" below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling with that slug already exists.`);
-}
-const order = options.order === null ? getNextOrder(siblings) : parseOrder(options.order);
-if (siblings.some((node) => node.pageOrder === order)) {
-	throw new Error(`Cannot use order ${String(order).padStart(3, '0')} below ${parent.pagePath ? `/${parent.pagePath}/` : '/'}. A sibling already uses it.`);
-}
-
-const directoryName = `${String(order).padStart(3, '0')}-${slug}`;
-const destination = path.join(parent.collectionDir, directoryName);
-const pagePath = [parent.pagePath, slug].filter(Boolean).join('/');
+if (!title || /[\r\n]/.test(title)) throw new Error(`A one-line page title is required.\n${usage}`);
+const plan = await planSiteNodeCreation({
+	siteRoot: siteDir, kind, title, slug: options.slug, order: options.order,
+	parentPath: options.parent, invocationDirectory: invocationRoot,
+});
+const { destination, pagePath } = plan;
 const action = options.dryRun ? 'Would create' : 'Created';
+if (!options.dryRun) await createSiteNode(plan);
 
-if (!options.dryRun) {
-	const createdCollection = await assertCollectionDirectory(parent.collectionDir);
-	try {
-		await writeNode({ destination, kind, title });
-	} catch (error) {
-		if (createdCollection) await rmdir(parent.collectionDir).catch(() => {});
-		throw error;
-	}
-}
-
-console.log(`${action} ${kind} "${title}" at ${toDisplayPath(destination)}.`);
-if (kind === 'page') {
-	console.log(`URL: /${pagePath}/`);
-} else {
-	console.log('This navigation category has no page or URL of its own.');
-	console.log(`Child URL prefix: /${pagePath}/`);
-}
+console.log(`${action} page "${title}" at ${toDisplayPath(destination)}.`);
+console.log(`URL: /${pagePath}/`);

package/scripts/build-site.mjs

@@ -9,9 +9,14 @@ const runScript = (relativePath, args = []) => runInherit(
 	{ cwd: siteProjectRoot },
 );
 
-await runScript('scripts/check-config.mjs');
-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');
+try {
+	await runScript('scripts/check-config.mjs');
+	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');
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+}

package/scripts/check-config.mjs

@@ -1,12 +1,11 @@
-import path from 'node:path';
-import { siteConfigLabel, sitePagesDir, sitePublicLabel, siteThemeLabel } from './lib/site-paths.mjs';
+import { siteConfigLabel, siteDir, sitePublicLabel } from './lib/site-paths.mjs';
 import { getLogoAssets, getPublicAssetInspection } from './lib/logo-assets.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';
-import { mergePageThemeConfig } from './lib/theme-presets.mjs';
+import { selectPageTheme } from './lib/theme-packages.mjs';
 
 const formatErrorMessage = (error) => {
 	if (error instanceof Error) {
@@ -21,26 +20,11 @@ try {
 	const themeConfig = await readThemeConfig();
 	const sitewideContent = await readSitewideContent();
 	const pageThemeFiles = await validatePageThemeFiles();
-	const pageThemesByDirectory = new Map(pageThemeFiles.map((file) => [path.dirname(file.path), file]));
-	for (const pageThemeFile of pageThemeFiles) {
-		const ancestorThemes = [];
-		let directory = path.dirname(pageThemeFile.path);
-		while (directory.startsWith(`${sitePagesDir}${path.sep}`)) {
-			const ancestorTheme = pageThemesByDirectory.get(directory);
-			if (ancestorTheme) ancestorThemes.unshift(ancestorTheme);
-			directory = path.dirname(directory);
-		}
-
-		const resolvedPageTheme = ancestorThemes.reduce(
-			(current, ancestor) => mergePageThemeConfig(current, ancestor.config),
-			themeConfig,
-		);
-		resolveThemeVisualConfig(resolvedPageTheme, pageThemeFile.label);
-	}
-	if (projectConfig.navigation.mode === 'tree') {
-		assertSectionBackgroundPatternCompatibility(themeConfig, siteThemeLabel, 'tree');
-		for (const pageThemeFile of pageThemeFiles) {
-			assertSectionBackgroundPatternCompatibility(pageThemeFile.config, pageThemeFile.label, 'tree');
+	for (const pageDirectory of new Set(['.', ...pageThemeFiles.map((file) => file.pageDirectory)])) {
+		const { treeTheme, selected } = await selectPageTheme({ siteRoot: siteDir, pageDirectory });
+		for (const theme of [treeTheme, selected]) {
+			resolveThemeVisualConfig(theme.config, theme.label);
+			if (projectConfig.navigation.mode === 'tree') assertSectionBackgroundPatternCompatibility(theme.config, theme.label, 'tree');
 		}
 	}
 	const logoAssets = getLogoAssets();

package/scripts/dev-local.mjs

@@ -18,12 +18,24 @@ const port = Number.parseInt(process.env.NORNA_DEV_PORT ?? '4321', 10);
 if (!Number.isInteger(port) || port < 1 || port > 65_535) {
 	throw new Error('NORNA_DEV_PORT must be an integer from 1 through 65535.');
 }
+const args = process.argv.slice(2);
+const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
+const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
+const shouldKillBlockingPort = args.includes('--kill');
+const shouldFollowLogs = args.includes('--follow');
+
 let projectConfig;
-try {
-	({ default: projectConfig } = await import('./lib/project-config.mjs'));
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
+if (['stop', 'status', 'logs'].includes(command)) {
+	// Recovery commands use the recorded server even while sources need conversion.
+	const recorded = await readFile(path.join(siteStateDir, 'dev', 'state.json'), 'utf8').then(JSON.parse).catch(() => null);
+	projectConfig = { site: { basePath: recorded?.url ? new URL(recorded.url).pathname : '/' } };
+} else {
+	try {
+		({ default: projectConfig } = await import('./lib/project-config.mjs'));
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
 }
 const localHost = '127.0.0.1';
 const localUrl = `http://${localHost}:${port}${projectConfig.site.basePath}`;
@@ -38,11 +50,6 @@ const legacyStatePath = path.join(astroCacheDir, 'dev-local.json');
 const astroStatePath = path.join(astroCacheDir, 'dev.json');
 const logPath = path.join(astroCacheDir, 'dev.log');
 const preparationLogPath = path.join(stateDirectory, 'preparation.log');
-const args = process.argv.slice(2);
-const knownCommands = new Set(['start', 'lan', 'status', 'logs', 'restart', 'stop']);
-const command = args.find((arg) => knownCommands.has(arg)) ?? args.find((arg) => !arg.startsWith('-')) ?? 'start';
-const shouldKillBlockingPort = args.includes('--kill');
-const shouldFollowLogs = args.includes('--follow');
 
 const runAstro = async (args, options = {}) => execFileAsync(process.execPath, getAstroArgs(args), {
 	cwd: siteProjectRoot,

package/scripts/export-theme-preset.mjs

@@ -4,7 +4,7 @@ import {
 	renderThemePresetReference,
 	themePresetNames,
 } from './lib/theme-presets.mjs';
-import { siteDir, siteThemeLabel } from './lib/site-paths.mjs';
+import { siteDir, siteDirLabel, siteThemeLabel } from './lib/site-paths.mjs';
 
 const [presetName, ...extraArgs] = process.argv.slice(2);
 
@@ -14,7 +14,7 @@ if (!presetName || extraArgs.length > 0) {
 
 const filename = `orig-${presetName}-theme.yaml`;
 const outputPath = path.join(siteDir, filename);
-const outputLabel = path.posix.join(path.posix.dirname(siteThemeLabel), filename);
+const outputLabel = path.posix.join(siteDirLabel, filename);
 const source = renderThemePresetReference(presetName, siteThemeLabel);
 
 try {

package/scripts/generate-images.mjs

@@ -1,3 +1,4 @@
+import { getPageImageSourceKey } from './lib/site-conventions.mjs';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
@@ -84,12 +85,12 @@ const getFilePathFromPublicPath = (publicPath) => path.join(astroPublicDir, publ
 const getSourceHashSlug = (sourceHash) => sourceHash.slice(0, sourceHashSlugLength);
 
 const getGeneratedPath = (sourceKey, sourceHash, width) => {
-	const parsed = path.parse(sourceKey);
+	const parsed = path.parse(sourceKey.replace(/^root\//, ''));
 	return path.join(generatedImagesDir, parsed.dir, `${parsed.name}-${getSourceHashSlug(sourceHash)}-${width}.webp`);
 };
 
 const getOriginalPath = (sourceKey, sourceHash) => {
-	const parsed = path.parse(sourceKey);
+	const parsed = path.parse(sourceKey.replace(/^root\//, ''));
 	return path.join(originalImagesDir, parsed.dir, `${parsed.name}-${getSourceHashSlug(sourceHash)}${parsed.ext}`);
 };
 
@@ -97,7 +98,7 @@ const fail = (message) => {
 	throw new Error(message);
 };
 
-const getImageSourceKey = (contentFile, image) => `pages/${contentFile.pageDirectory}/images/${image}`;
+const getImageSourceKey = (contentFile, image) => getPageImageSourceKey(contentFile.pageDirectory, image);
 
 const getReferencedImages = async (contentFile) => {
 	const { body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
@@ -262,7 +263,7 @@ const hasGeneratedVariants = async (variants) => {
 	return true;
 };
 
-const getReusableEntry = async (sourcePath, previousEntry, sourceHash) => {
+const getReusableEntry = async (sourceKey, previousEntry, sourceHash) => {
 	if (
 		previousEntry?.sourceHash !== sourceHash
 		|| previousEntry?.outputVersion !== imageOutputVersion
@@ -272,7 +273,7 @@ const getReusableEntry = async (sourcePath, previousEntry, sourceHash) => {
 		return null;
 	}
 
-	const variants = getVariants(sourcePath, sourceHash, getVariantWidths(previousEntry));
+	const variants = getVariants(sourceKey, sourceHash, getVariantWidths(previousEntry));
 
 	if (!(await hasGeneratedVariants(variants))) {
 		return null;
@@ -393,7 +394,7 @@ for (const { sourcePath, sourceKey } of sources) {
 		continue;
 	}
 
-	const reusableEntry = await getReusableEntry(sourcePath, previousManifest[sourceKey], sourceHash);
+	const reusableEntry = await getReusableEntry(sourceKey, previousManifest[sourceKey], sourceHash);
 
 	if (reusableEntry) {
 		manifest[sourceKey] = reusableEntry;

package/scripts/generate-schemas.mjs

@@ -3,22 +3,23 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'astro/zod';
 import {
-	categorySchema,
 	configSchema,
+	rootThemeSchema,
 	pageThemeSchema,
 	siteSchema,
 	sitewideSchema,
 	themeVisualSchema,
 } from './lib/schema-definitions.mjs';
 import { applySchemaEditorMetadata } from './lib/schema-editor-metadata.mjs';
+import { sourceFileDefinitions, sourcePageDirectoryPattern } from './lib/source-files.mjs';
 import { getNornaBlockSchema } from './lib/norna-markdown-blocks.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const schemaDirectory = path.join(root, 'schemas');
 const definitions = [
-	['category.schema.json', 'Norna page category', categorySchema],
 	['config.schema.json', 'Norna site configuration', configSchema],
-	['theme.schema.json', 'Norna visual theme', themeVisualSchema],
+	['theme.schema.json', 'Norna inherited tree theme', themeVisualSchema],
+	['root-theme.schema.json', 'Norna root tree theme', rootThemeSchema],
 	['page-theme.schema.json', 'Norna page theme', pageThemeSchema],
 	['sitewide-content.schema.json', 'Norna site-wide content', sitewideSchema],
 	['content-frontmatter.schema.json', 'Norna page frontmatter', siteSchema],
@@ -44,15 +45,17 @@ for (const type of blockTypes) {
 }
 
 schemaFiles.set('manifest.json', `${JSON.stringify({
-	editorApiVersion: 2,
-	schemaVersion: 3,
+	editorApiVersion: 3,
+	schemaVersion: 6,
+	sourceFiles: sourceFileDefinitions,
+	pageDirectoryPattern: sourcePageDirectoryPattern,
 	blockSchemas: Object.fromEntries(blockTypes.map((type) => [type, `${type}.schema.json`])),
 	files: {
-		category: 'category.schema.json',
 		config: 'config.schema.json',
 		contentFrontmatter: 'content-frontmatter.schema.json',
 		sitewideContent: 'sitewide-content.schema.json',
 		theme: 'theme.schema.json',
+		rootTheme: 'root-theme.schema.json',
 		pageTheme: 'page-theme.schema.json',
 	},
 }, null, 2)}\n`);

package/scripts/lib/category-destinations.mjs

@@ -9,28 +9,28 @@ export const createCategoryDestinationModel = (nodes) => {
 	const visit = (branch) => {
 		const { node } = branch;
 		if (node.navigation?.listed === false) return false;
-		const children = branch.children.filter(({ node: child }) => child.navigation?.listed !== false);
-		const reachable = children.map(visit).some(Boolean);
+		// Empty child categories retain their URLs but do not become menu choices
+		// or redirect targets for a parent that still has reachable pages.
+		const children = branch.children.filter(visit);
 		if (node.kind !== 'category') return true;
-		if (!reachable) {
+		if (children.length === 0) {
 			const source = node.categorySourceLabel ?? node.nodeLabel ?? node.pageDirectory;
 			diagnostics.push({
 				code: 'category-without-listed-content',
-				severity: 'error',
+				severity: 'warning',
 				message: `${source} has no listed reachable content page.`,
-				fix: 'Add a listed page under this category, or remove the category.',
+				fix: 'Add a listed page to include this category in navigation, or leave it empty while reorganizing.',
 			});
-			return false;
 		}
-		const first = children[0].node;
+		const first = children[0]?.node;
 		destinations.push({
 			category: node,
 			pathname: getSiteNodePathname(node),
-			kind: first.kind === 'page' ? 'redirect' : 'listing',
-			target: first.kind === 'page' ? first : null,
+			kind: first?.kind === 'page' ? 'redirect' : 'listing',
+			target: first?.kind === 'page' ? first : null,
 			children: children.map(({ node: child }) => child),
 		});
-		return true;
+		return children.length > 0;
 	};
 	getSiteNavigationTree(nodes.map((node) => ({ node }))).forEach(visit);
 	return {
@@ -41,8 +41,9 @@ export const createCategoryDestinationModel = (nodes) => {
 };
 
 export const assertCategoryDestinationModel = (model) => {
-	if (model.diagnostics.length) {
-		throw new Error(model.diagnostics.map(({ message, fix }) => `${message}\n${fix}`).join('\n'));
+	const errors = model.diagnostics.filter(({ severity }) => severity === 'error');
+	if (errors.length) {
+		throw new Error(errors.map(({ message, fix }) => `${message}\n${fix}`).join('\n'));
 	}
 	return model;
 };

package/scripts/lib/documentation-links.mjs

@@ -1,8 +1,39 @@
 import packageJson from '../../package.json' with { type: 'json' };
+import routes from './documentation-routes.json' with { type: 'json' };
+
+const websiteRoot = 'https://janga.github.io/norna/reference/';
+const repositoryRoot = 'https://github.com/janga/norna/blob/';
+
+// Release tags through 0.7.26 contain the reference under docs/. Newer tags
+// contain its single authored source in the documentation site's page tree.
+export const usesLegacyReference = (version) => {
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version ?? '');
+	if (!match) return false;
+	const [major, minor, patch] = match.slice(1).map(Number);
+	return major === 0 && (minor < 7 || (minor === 7 && patch <= 26));
+};
+
+const referenceDestination = (file, anchor) => {
+	const target = routes.legacy[`${file}#${anchor}`] ?? routes.legacy[file];
+	if (!target) throw new Error(`Unknown documentation destination: ${file}${anchor ? `#${anchor}` : ''}`);
+	const [route, targetAnchor] = target.split('#');
+	const source = routes.sources[route];
+	if (!source) throw new Error(`Missing documentation source for ${route}`);
+	return { route, source, anchor: targetAnchor, url: websiteRoot + target };
+};
+
+export const documentationLinkForVersion = (version, label, file, anchor) => {
+	const destination = referenceDestination(file, anchor);
+	const reference = version ? `v${version}` : 'main';
+	const source = usesLegacyReference(version)
+		? `docs/${file}${anchor ? `#${anchor}` : ''}`
+		: `${version === '0.7.27' ? destination.source.replace('site/root/pages/', 'site/pages/') : destination.source}${destination.anchor ? `#${destination.anchor}` : ''}`;
+	const sourceLabel = version ? `Norna ${version} source reference` : 'Reference source';
+	return `[${label} (current)](${destination.url})\n\n[${sourceLabel}](${repositoryRoot}${reference}/${source})`;
+};
 
 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}` : ''})`
+	documentationLinkForVersion(packageJson.version, label, file, anchor)
 );