@janga/norna 0.7.11 → 0.7.13

package/scripts/deploy-site.mjs

@@ -12,7 +12,7 @@ import {
 	extractNornaMarkdownBlocks,
 	getNornaBlockImageReferences,
 } from './lib/norna-markdown-blocks.mjs';
-import { projectConfig } from './lib/project-config.mjs';
+import { getGitHubRepositoryContext, githubPagesWorkflow } from './lib/github-repository.mjs';
 import {
 	engineRoot,
 	generatedImagesManifestLabel,
@@ -28,9 +28,9 @@ import {
 const execFileAsync = promisify(execFile);
 
 const root = siteProjectRoot;
-const branch = projectConfig.github.branch;
-const repo = projectConfig.github.repo;
-const pagesWorkflow = projectConfig.github.pagesWorkflow;
+const pagesWorkflow = githubPagesWorkflow;
+let branch;
+let repo;
 const args = process.argv.slice(2);
 const mode = args[0] === 'commit' ? 'commit' : 'deploy';
 const modeArgs = mode === 'commit' ? args.slice(1) : args;
@@ -53,9 +53,9 @@ const failedConclusions = new Set(['action_required', 'cancelled', 'failure', 's
 const deployUsage = [
 	'Usage: norna deploy',
 	'',
-	`Publishes an already committed ${branch} branch: builds, verifies a clean worktree,`,
-	`pushes ${branch} when local ${branch} is ahead of origin/${branch}, and checks GitHub Pages.`,
-	`If local ${branch} already matches origin/${branch}, it skips push and checks Pages.`,
+	'Publishes an already committed default branch: builds, verifies a clean worktree,',
+	'pushes it when local HEAD is ahead of origin, and checks GitHub Pages.',
+	'If local HEAD already matches origin, it skips push and checks Pages.',
 	'',
 	'For the old build-and-commit convenience flow, use:',
 	'norna deploy:commit "Commit message"',
@@ -63,7 +63,7 @@ const deployUsage = [
 const deployCommitUsage = [
 	'Usage: norna deploy:commit "Commit message"',
 	'',
-	`Builds, stages only allowed site changes, commits, pushes ${branch},`,
+	'Builds, stages only allowed site changes, commits, pushes the default branch,',
 	'and checks GitHub Pages.',
 ].join('\n');
 
@@ -385,6 +385,10 @@ if (modeArgs.includes('--help') || modeArgs.includes('-h')) {
 }
 
 try {
+	const githubRepository = await getGitHubRepositoryContext({ cwd: root });
+	branch = githubRepository.branch;
+	repo = githubRepository.repo;
+
 	if (mode === 'commit') {
 		await deployWithCommit();
 	} else {

package/scripts/lib/example-sites.mjs

@@ -13,6 +13,9 @@ export const getExampleSites = async (root) => {
 
 		for (const entry of entries.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
 			const siteDirectory = path.join(categoryDirectory, entry.name, 'site');
+			if (!existsSync(path.join(siteDirectory, 'config.md'))) {
+				throw new Error(`Example ${path.relative(root, siteDirectory)} is missing config.md.`);
+			}
 			if (!existsSync(path.join(siteDirectory, 'content.md'))) {
 				throw new Error(`Example ${path.relative(root, siteDirectory)} is missing content.md.`);
 			}

package/scripts/lib/github-repository.mjs

@@ -0,0 +1,44 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export const githubPagesWorkflow = 'deploy.yml';
+
+export const getGitHubRepositoryContext = async ({ cwd, repo } = {}) => {
+	const args = [
+		'repo',
+		'view',
+		...(repo ? [repo] : []),
+		'--json',
+		'nameWithOwner,defaultBranchRef',
+	];
+	let stdout;
+
+	try {
+		({ stdout } = await execFileAsync('gh', args, {
+			cwd,
+			maxBuffer: 1024 * 1024,
+		}));
+	} catch (error) {
+		throw new Error([
+			'Could not discover the GitHub repository and its default branch.',
+			'Run this command in a Git repository with a GitHub remote and an authenticated gh CLI, or pass explicit deploy:watch options.',
+			error.stderr?.trim(),
+			error.message,
+		].filter(Boolean).join('\n'));
+	}
+
+	const result = JSON.parse(stdout || '{}');
+	const defaultBranch = result.defaultBranchRef?.name;
+	const nameWithOwner = result.nameWithOwner;
+
+	if (!nameWithOwner || !defaultBranch) {
+		throw new Error('GitHub did not report a repository name and default branch.');
+	}
+
+	return Object.freeze({
+		branch: defaultBranch,
+		repo: nameWithOwner,
+	});
+};

package/scripts/lib/norna-markdown-blocks.mjs

@@ -589,7 +589,8 @@ export const splitNornaMarkdownBlockMarkers = (html, options = {}) => {
 const normalizeBlockSource = (source) => source.replace(/\r\n?/g, '\n').trim();
 
 const inlineNoteReferenceRegex = /\{note-ref\}/g;
-const inlineNoteDeclarationRegex = /^\s*\{note:\s*(.*)\}\s*$/;
+const inlineNoteDeclarationOpeningRegex = /^\s*\{note:\s*(.*)$/;
+const inlineNoteDeclarationClosingRegex = /^(.*?)\}\s*$/;
 const inlineNoteDeclarationStartRegex = /\{note(?:\s*:|\s*\})/;
 
 const maskInlineCodeAndComments = (source) => source.replace(
@@ -605,7 +606,82 @@ const formatInlineNoteError = (message, options, line) => ({
 	message: failMessage(message, { ...options, line }),
 });
 
-const getInlineNoteErrorMessage = () => 'Write the note on its own line as "{note: Your explanatory text.}".';
+const getInlineNoteErrorMessage = () => 'Write the note on its own line as "{note: Short text.}", or end a multiline note with "}".';
+
+const findUnescapedInlineNoteConstruct = (source) => {
+	const constructRegex = /\{note(?:-ref\}|\s*:|\s*\})/g;
+
+	for (const match of source.matchAll(constructRegex)) {
+		const index = match.index ?? 0;
+		let precedingBackslashes = 0;
+		for (let cursor = index - 1; cursor >= 0 && source[cursor] === '\\'; cursor -= 1) {
+			precedingBackslashes += 1;
+		}
+
+		if (precedingBackslashes % 2 === 0) {
+			return match[0].startsWith('{note-ref') ? 'reference' : 'note';
+		}
+	}
+
+	return null;
+};
+
+const collectInlineNoteDeclaration = (lines, maskedLines, startIndex) => {
+	const openingMatch = (lines[startIndex] ?? '').match(inlineNoteDeclarationOpeningRegex);
+	if (!openingMatch) return null;
+	const maskedOpeningMatch = (maskedLines[startIndex] ?? '').match(inlineNoteDeclarationOpeningRegex);
+
+	const textLines = [];
+	let currentLine = openingMatch[1] ?? '';
+	let currentMaskedLine = maskedOpeningMatch?.[1] ?? '';
+
+	for (let index = startIndex; index < lines.length; index += 1) {
+		const conflictType = findUnescapedInlineNoteConstruct(currentMaskedLine);
+		if (conflictType) {
+			return {
+				closed: false,
+				conflictIndex: index,
+				conflictType,
+				endIndex: index,
+				text: textLines.map((line) => line.trim()).filter(Boolean).join(' '),
+			};
+		}
+
+		const closingMatch = currentLine.match(inlineNoteDeclarationClosingRegex);
+		if (closingMatch) {
+			textLines.push(closingMatch[1]);
+			return {
+				closed: true,
+				endIndex: index,
+				text: textLines.map((line) => line.trim()).filter(Boolean).join(' '),
+			};
+		}
+
+		textLines.push(currentLine);
+		currentLine = lines[index + 1] ?? '';
+		currentMaskedLine = maskedLines[index + 1] ?? '';
+	}
+
+	return {
+		closed: false,
+		endIndex: lines.length - 1,
+		text: textLines.map((line) => line.trim()).filter(Boolean).join(' '),
+	};
+};
+
+const getUnclosedInlineNoteMessage = (noteDeclaration, startLine, lineOffset = 0) => {
+	if (noteDeclaration.conflictType === 'note') {
+		const conflictLine = lineOffset + noteDeclaration.conflictIndex + 1;
+		return `The note starting on line ${startLine} is not closed before another note starts on line ${conflictLine}. Close the first note with "}".`;
+	}
+
+	if (noteDeclaration.conflictType === 'reference') {
+		const conflictLine = lineOffset + noteDeclaration.conflictIndex + 1;
+		return `The note starting on line ${startLine} contains "{note-ref}" on line ${conflictLine}. Close the note before adding a note reference.`;
+	}
+
+	return `The note starting on line ${startLine} is not closed. End it with "}" on its own line or at the end of the note text.`;
+};
 
 /**
  * Finds the deliberately small inline-note syntax while ignoring fenced and
@@ -640,8 +716,7 @@ export const extractInlineNoteDiagnostics = (markdown, options = {}) => {
 		pendingParagraph = null;
 	};
 
-	const attachNote = (noteMatch, lineNumber) => {
-		const text = noteMatch[1].trim();
+	const attachNote = (text, lineNumber) => {
 		if (!text) {
 			addError(`The note on line ${lineNumber} is empty. ${getInlineNoteErrorMessage()}`, lineNumber);
 			pendingParagraph = null;
@@ -686,7 +761,10 @@ export const extractInlineNoteDiagnostics = (markdown, options = {}) => {
 
 		const trimmed = line.trim();
 		const maskedTrimmed = maskedLine.trim();
-		const noteMatch = trimmed.match(inlineNoteDeclarationRegex);
+		const startsNoteDeclaration = inlineNoteDeclarationOpeningRegex.test(maskedLine);
+		const noteDeclaration = startsNoteDeclaration
+			? collectInlineNoteDeclaration(lines, maskedLines, index)
+			: null;
 		const looksLikeNoteDeclaration = inlineNoteDeclarationStartRegex.test(maskedTrimmed);
 		const referenceCount = countInlineNoteReferences(maskedLine);
 		const isHeading = /^#{1,6}(?:\s|$)/.test(trimmed);
@@ -698,8 +776,14 @@ export const extractInlineNoteDiagnostics = (markdown, options = {}) => {
 		}
 
 		if (pendingParagraph) {
-			if (noteMatch) {
-				attachNote(noteMatch, lineNumber);
+			if (noteDeclaration) {
+				if (!noteDeclaration.closed) {
+					addError(getUnclosedInlineNoteMessage(noteDeclaration, lineNumber, options.lineOffset), lineNumber);
+					pendingParagraph = null;
+				} else {
+					attachNote(noteDeclaration.text, lineNumber);
+				}
+				index = noteDeclaration.endIndex;
 				continue;
 			}
 
@@ -716,13 +800,16 @@ export const extractInlineNoteDiagnostics = (markdown, options = {}) => {
 			noteJustSeen = false;
 		}
 
-		if (noteMatch || looksLikeNoteDeclaration) {
+		if (noteDeclaration || looksLikeNoteDeclaration) {
 			addError(
-				noteMatch
-					? `A "{note: ...}" requires a preceding paragraph containing "{note-ref}".`
+				noteDeclaration
+					? noteDeclaration.closed
+						? `A "{note: ...}" requires a preceding paragraph containing "{note-ref}".`
+						: getUnclosedInlineNoteMessage(noteDeclaration, lineNumber, options.lineOffset)
 					: `Invalid note syntax on line ${lineNumber}. ${getInlineNoteErrorMessage()}`,
 				lineNumber,
 			);
+			if (noteDeclaration) index = noteDeclaration.endIndex;
 			continue;
 		}
 

package/scripts/lib/project-config.mjs

@@ -1,9 +1,55 @@
-import { pathToFileURL } from 'node:url';
-import { siteConfigLabel, siteConfigPath, siteThemeLabel } from './site-paths.mjs';
+import { access, readFile } from 'node:fs/promises';
+import { parseYamlMapping } from './frontmatter-yaml.mjs';
+import {
+	splitSiteFile,
+	validateConfigFrontmatterStructure,
+	validateFrontmatterIndentation,
+} from './site-content.mjs';
+import {
+	legacySiteConfigPath,
+	siteConfigLabel,
+	siteConfigPath,
+	siteThemeLabel,
+} from './site-paths.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
 
-const { default: siteConfig } = await import(/* @vite-ignore */ pathToFileURL(siteConfigPath).href);
+const fileExists = (filePath) => access(filePath).then(() => true, () => false);
+const readSiteConfig = async () => {
+	const source = await readFile(siteConfigPath, 'utf8').catch(async (error) => {
+		if (error?.code === 'ENOENT' && await fileExists(legacySiteConfigPath)) {
+			throw new Error(`${siteConfigLabel} is required. Replace the obsolete config.mjs with a frontmatter-only config.md file.`);
+		}
+
+		if (error?.code === 'ENOENT') {
+			throw new Error(`${siteConfigLabel} is required. Create it before running Norna.`);
+		}
+
+		throw error;
+	});
+	const { body, frontmatter, frontmatterBody } = splitSiteFile(source, siteConfigLabel);
+	const issues = [];
+
+	validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
+	validateConfigFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
+
+	if (body.trim()) {
+		issues.push({
+			message: `${siteConfigLabel} may contain YAML frontmatter only. Remove the Markdown body.`,
+		});
+	}
+
+	if (issues.length > 0) {
+		throw new Error([
+			`${siteConfigLabel} has invalid frontmatter.`,
+			...issues.map((issue) => `- ${issue.message}`),
+		].join('\n'));
+	}
+
+	return parseYamlMapping(frontmatterBody);
+};
+
+const siteConfig = await readSiteConfig();
 const themeConfig = await readThemeConfig();
 
 const cssLengthPattern = String.raw`(?:\d+|\d*\.\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)`;
@@ -28,16 +74,6 @@ const readEnum = (object, key, path, allowedValues, fallback, sourceLabel = site
 	return value;
 };
 
-const readString = (object, key, path, sourceLabel = siteConfigLabel) => {
-	const value = object[key];
-
-	if (typeof value !== 'string' || value.trim() === '') {
-		throw new Error(`${path}.${key} must be a non-empty string in ${sourceLabel}.`);
-	}
-
-	return value.trim();
-};
-
 const readFontFamily = (object, key, path, fallback, sourceLabel = siteConfigLabel) => {
 	const value = object[key] ?? fallback;
 
@@ -138,123 +174,82 @@ const readResponsivePercent = (object, key, path, fallback, sourceLabel = siteCo
 	});
 };
 
-const readBoolean = (object, key, path, fallback) => {
-	const value = object[key] ?? fallback;
-
-	if (typeof value !== 'boolean') {
-		throw new Error(`${path}.${key} must be a boolean in ${siteConfigLabel}.`);
-	}
-
-	return value;
-};
-
-const readPositiveInteger = (object, key, path, fallback) => {
-	const value = object[key] ?? fallback;
+const readSiteUrl = (config) => {
+	const configuredValue = process.env.NORNA_SITE_URL ?? config.url;
 
-	if (!Number.isInteger(value) || value <= 0) {
-		throw new Error(`${path}.${key} must be a positive integer in ${siteConfigLabel}.`);
+	if (typeof configuredValue !== 'string' || configuredValue.trim() === '') {
+		throw new Error(`url must be a non-empty absolute URL in ${siteConfigLabel}.`);
 	}
 
-	return value;
-};
-
-const readPositiveNumber = (object, key, path, fallback) => {
-	const value = object[key] ?? fallback;
-
-	if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-		throw new Error(`${path}.${key} must be a positive number in ${siteConfigLabel}.`);
-	}
-
-	return value;
-};
-
-const readUrl = (object, key, path) => {
-	const value = readString(object, key, path);
-
+	let url;
 	try {
-		return new URL(value).href;
+		url = new URL(configuredValue.trim());
 	} catch {
-		throw new Error(`${path}.${key} must be an absolute URL in ${siteConfigLabel}.`);
+		throw new Error(`url must be an absolute URL such as "https://example.com/" in ${siteConfigLabel}.`);
 	}
-};
 
-const readBasePath = (object, key, path) => {
-	const value = object[key] ?? '/';
-
-	if (typeof value !== 'string' || value.trim() === '') {
-		throw new Error(`${path}.${key} must be a non-empty URL path in ${siteConfigLabel}.`);
+	if (!['http:', 'https:'].includes(url.protocol)) {
+		throw new Error(`url must use http or https in ${siteConfigLabel}.`);
 	}
-
-	const normalizedValue = value.trim();
-
-	if (
-		!normalizedValue.startsWith('/')
-		|| !normalizedValue.endsWith('/')
-		|| normalizedValue.includes('//')
-		|| /[\s?#]/.test(normalizedValue)
-	) {
-		throw new Error(`${path}.${key} must start and end with "/" and must not contain whitespace, "?", "#", or "//" in ${siteConfigLabel}.`);
+	if (url.search || url.hash) {
+		throw new Error(`url must not contain a query string or fragment in ${siteConfigLabel}.`);
+	}
+	if (!url.pathname.endsWith('/')) {
+		url.pathname = `${url.pathname}/`;
+	}
+	if (url.pathname.includes('//')) {
+		throw new Error(`url must not contain repeated slashes in its path in ${siteConfigLabel}.`);
 	}
 
-	return normalizedValue;
+	return url;
 };
 
-const readSmoothScroll = (navigation) => {
-	const rawSmoothScroll = assertObject(navigation.smoothScroll ?? {}, 'navigation.smoothScroll');
-	const minimumDurationMs = readPositiveInteger(rawSmoothScroll, 'minimumDurationMs', 'navigation.smoothScroll', 2_000);
-	const maximumDurationMs = readPositiveInteger(rawSmoothScroll, 'maximumDurationMs', 'navigation.smoothScroll', 4_000);
+const localeLabels = Object.freeze({
+	en: Object.freeze({
+		dismissBanner: 'Dismiss notice',
+		gallery: 'Images',
+		note: 'Note',
+		pageNavigation: 'On this page',
+		siteBanners: 'Site notices',
+		siteNavigation: 'Pages',
+		skipToContent: 'Skip to content',
+	}),
+	sv: Object.freeze({
+		dismissBanner: 'Stäng meddelande',
+		gallery: 'Bilder',
+		note: 'Not',
+		pageNavigation: 'På den här sidan',
+		siteBanners: 'Meddelanden',
+		siteNavigation: 'Sidor',
+		skipToContent: 'Hoppa till innehållet',
+	}),
+});
 
-	if (maximumDurationMs < minimumDurationMs) {
-		throw new Error(`navigation.smoothScroll.maximumDurationMs must be greater than or equal to minimumDurationMs in ${siteConfigLabel}.`);
-	}
+const readLocale = (config) => {
+	const lang = config.language ?? 'en';
 
-	return Object.freeze({
-		durationPerPixelMs: readPositiveNumber(rawSmoothScroll, 'durationPerPixelMs', 'navigation.smoothScroll', 0.22),
-		enabled: readBoolean(rawSmoothScroll, 'enabled', 'navigation.smoothScroll', true),
-		maximumDurationMs,
-		minimumDurationMs,
-	});
-};
+	if (typeof lang !== 'string' || !/^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]+)*$/.test(lang.trim())) {
+		throw new Error(`language must be a valid language tag such as "en" or "sv" in ${siteConfigLabel}.`);
+	}
 
-const readLocale = (rawLocale) => {
-	const locale = assertObject(rawLocale ?? {}, 'locale');
-	const labels = assertObject(locale.labels ?? {}, 'locale.labels');
-	const lang = locale.lang ?? 'en';
+	const normalizedLang = lang.trim();
+	const languageKey = normalizedLang.toLowerCase().split('-')[0];
+	const labels = localeLabels[languageKey];
 
-	if (typeof lang !== 'string' || !/^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]+)*$/.test(lang.trim())) {
-		throw new Error(`locale.lang must be a valid language tag such as "en" or "sv" in ${siteConfigLabel}.`);
+	if (!labels) {
+		throw new Error(`language "${normalizedLang}" has no built-in Norna UI text. Supported languages: ${Object.keys(localeLabels).join(', ')}.`);
 	}
 
 	return Object.freeze({
-		lang: lang.trim(),
-		labels: Object.freeze({
-			closeMenu: readString({ closeMenu: labels.closeMenu ?? 'Close menu' }, 'closeMenu', 'locale.labels'),
-			dismissBanner: readString({ dismissBanner: labels.dismissBanner ?? 'Dismiss notice' }, 'dismissBanner', 'locale.labels'),
-			skipToContent: readString({ skipToContent: labels.skipToContent ?? 'Skip to content' }, 'skipToContent', 'locale.labels'),
-			sectionNavigation: readString({ sectionNavigation: labels.sectionNavigation ?? 'Sections' }, 'sectionNavigation', 'locale.labels'),
-			gallery: readString({ gallery: labels.gallery ?? 'Images' }, 'gallery', 'locale.labels'),
-			note: readString({ note: labels.note ?? 'Note' }, 'note', 'locale.labels'),
-			menu: readString({ menu: labels.menu ?? 'Menu' }, 'menu', 'locale.labels'),
-			pageNavigation: readString({ pageNavigation: labels.pageNavigation ?? 'On this page' }, 'pageNavigation', 'locale.labels'),
-			siteNavigation: readString({ siteNavigation: labels.siteNavigation ?? 'Pages' }, 'siteNavigation', 'locale.labels'),
-			siteBanners: readString({ siteBanners: labels.siteBanners ?? 'Site notices' }, 'siteBanners', 'locale.labels'),
-		}),
+		lang: normalizedLang,
+		labels,
 	});
 };
 
-const rawConfig = assertObject(siteConfig, 'default export');
-const misplacedThemeKeys = ['layout', 'gallery', 'typography'].filter((key) => key in rawConfig);
-if (misplacedThemeKeys.length > 0) {
-	throw new Error(`${misplacedThemeKeys.join(', ')} belong in ${siteThemeLabel}, not ${siteConfigLabel}.`);
-}
-
+const rawConfig = assertObject(siteConfig, 'config frontmatter');
 const rawTheme = assertObject(themeConfig, 'theme frontmatter', siteThemeLabel);
-const rawSite = assertObject(rawConfig.site, 'site');
-const rawNavigation = assertObject(rawConfig.navigation ?? {}, 'navigation');
-const rawLocale = rawConfig.locale ?? {};
-const rawGithub = assertObject(rawConfig.github, 'github');
-const rawDeploy = assertObject(rawConfig.deploy ?? {}, 'deploy');
-const rawDeployWatch = assertObject(rawDeploy.watch ?? {}, 'deploy.watch');
+const siteUrl = readSiteUrl(rawConfig);
+const scrollBehaviorNames = ['instant', 'browser-smooth'];
 
 const defaultFontFamily = "Arial, 'Helvetica Neue', Helvetica, sans-serif";
 const layoutDensityNames = ['compact', 'normal', 'airy'];
@@ -383,26 +378,20 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 
 export const projectConfig = Object.freeze({
 	site: Object.freeze({
-		basePath: readBasePath(rawSite, 'basePath', 'site'),
-		url: readUrl(rawSite, 'url', 'site'),
+		basePath: siteUrl.pathname,
+		url: siteUrl.href,
 	}),
 	...resolveThemeVisualConfig(rawTheme, siteThemeLabel),
 	navigation: Object.freeze({
-		smoothScroll: readSmoothScroll(rawNavigation),
-	}),
-	locale: readLocale(rawLocale),
-	github: Object.freeze({
-		repo: readString(rawGithub, 'repo', 'github'),
-		branch: readString(rawGithub, 'branch', 'github'),
-		pagesWorkflow: readString(rawGithub, 'pagesWorkflow', 'github'),
-	}),
-	deploy: Object.freeze({
-		watch: Object.freeze({
-			intervalMs: readPositiveInteger(rawDeployWatch, 'intervalMs', 'deploy.watch', 10_000),
-			timeoutMs: readPositiveInteger(rawDeployWatch, 'timeoutMs', 'deploy.watch', 15 * 60_000),
-			runLimit: readPositiveInteger(rawDeployWatch, 'runLimit', 'deploy.watch', 10),
-		}),
+		scrollBehavior: readEnum(
+			rawConfig,
+			'scrollBehavior',
+			'config frontmatter',
+			scrollBehaviorNames,
+			'instant',
+		),
 	}),
+	locale: readLocale(rawConfig),
 });
 
 export default projectConfig;

package/scripts/lib/site-content.mjs

@@ -20,6 +20,7 @@ const h2Regex = /^##\s+.*$/gm;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const deprecatedInlineStyleReferenceRegex = /\[[^\]\n]+\]\{\.([a-z][a-z0-9-]*)\}/g;
 const frontmatterDelimiterRegex = /^---\s*$/;
+const knownConfigTopLevelFrontmatterKeys = new Set(['url', 'language', 'scrollBehavior']);
 const knownContentTopLevelFrontmatterKeys = new Set(['title', 'description', 'navigation', 'sections']);
 const knownThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
 const knownRouteThemeTopLevelFrontmatterKeys = new Set(['navigation', 'preset', 'layout', 'gallery', 'typography', 'presentation']);
@@ -270,6 +271,12 @@ export const validateContentFrontmatterStructure = (frontmatter, addIssue) =>
 		fileKind: 'content',
 	});
 
+export const validateConfigFrontmatterStructure = (frontmatter, addIssue) =>
+	validateFrontmatterStructure(frontmatter, addIssue, {
+		knownTopLevelFrontmatterKeys: knownConfigTopLevelFrontmatterKeys,
+		fileKind: 'config',
+	});
+
 export const validateThemeFrontmatterStructure = (frontmatter, addIssue) =>
 	validateFrontmatterStructure(frontmatter, addIssue, {
 		knownTopLevelFrontmatterKeys: knownThemeTopLevelFrontmatterKeys,

package/scripts/lib/site-paths.mjs

@@ -22,7 +22,10 @@ export const invocationRoot = configuredInvocationRoot
 
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
-		existsSync(path.join(siteDir, 'config.mjs'))
+		(
+			existsSync(path.join(siteDir, 'config.md'))
+			|| existsSync(path.join(siteDir, 'config.mjs'))
+		)
 		&& existsSync(path.join(siteDir, 'content.md'))
 	);
 };
@@ -114,7 +117,8 @@ const getPathLabel = (filePath) => {
 };
 
 export const siteDir = resolvedSitePaths.siteDir;
-export const siteConfigPath = path.join(siteDir, 'config.mjs');
+export const siteConfigPath = path.join(siteDir, 'config.md');
+export const legacySiteConfigPath = path.join(siteDir, 'config.mjs');
 export const siteThemePath = path.join(siteDir, 'theme.md');
 export const siteContentPath = path.join(siteDir, 'content.md');
 export const sitewideContentPath = path.join(siteDir, 'sitewide-content.md');