@janga/norna 0.7.8 → 0.7.10

package/src/lib/routeThemes.ts

@@ -0,0 +1,61 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseYamlMapping } from '../../scripts/lib/frontmatter-yaml.mjs';
+import {
+	splitSiteFile,
+	validateFrontmatterIndentation,
+	validateRouteThemeFrontmatterStructure,
+} from '../../scripts/lib/site-content.mjs';
+import { siteRoutesDir, siteRoutesLabel, sitewideContentLabel } from '../../scripts/lib/site-paths.mjs';
+import { themeVisualSchema } from '../content.config';
+
+type RouteTheme = {
+	id: string;
+	data: Record<string, unknown>;
+};
+
+export const getRouteTheme = async (routeDirectory: string | null): Promise<RouteTheme | null> => {
+	if (!routeDirectory) return null;
+
+	const segments = routeDirectory.split(/[\\/]/).filter(Boolean);
+	for (let length = segments.length; length > 0; length -= 1) {
+		const themeSegments = segments.slice(0, length);
+		const themePath = path.join(siteRoutesDir, ...themeSegments, 'theme.md');
+		const themeLabel = `${siteRoutesLabel}/${themeSegments.join('/')}/theme.md`;
+		const source = await readFile(themePath, 'utf8').catch((error) => {
+			if (error?.code === 'ENOENT') return null;
+			throw error;
+		});
+		if (!source) continue;
+
+		const { frontmatter, frontmatterBody } = splitSiteFile(source, themeLabel);
+		const issues: Array<{ message: string }> = [];
+		validateFrontmatterIndentation(frontmatter, (issue) => issues.push(issue));
+		validateRouteThemeFrontmatterStructure(frontmatter, (issue) => issues.push(issue));
+		if (issues.length > 0) {
+			throw new Error([
+				`${themeLabel} has invalid frontmatter.`,
+				...issues.map((issue) => `- ${issue.message}`),
+			].join('\n'));
+		}
+
+		const data = parseYamlMapping(frontmatterBody);
+		if (Object.hasOwn(data, 'navigation')) {
+			throw new Error(`${themeLabel} may not define navigation. Brand and logo belong in ${sitewideContentLabel}.`);
+		}
+		const parsed = themeVisualSchema.safeParse(data);
+		if (!parsed.success) {
+			throw new Error([
+				`${themeLabel} has invalid values.`,
+				...parsed.error.issues.map((issue) => `- ${issue.path.join('.') || '(root)'}: ${issue.message}`),
+			].join('\n'));
+		}
+
+		return {
+			id: `routes/${themeSegments.join('/')}/theme`,
+			data: parsed.data,
+		};
+	}
+
+	return null;
+};

package/src/lib/sectionContent.ts

@@ -1,6 +1,8 @@
 import type { CollectionEntry } from 'astro:content';
+import { markdownToHtml } from 'satteri';
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import {
+	extractInlineNoteDiagnostics,
 	extractNornaMarkdownBlocks,
 	splitNornaMarkdownBlockMarkers,
 	splitNornaRenderedCodeBlocks,
@@ -10,8 +12,6 @@ import type { SitePage } from './sitePages';
 
 type SiteSectionMetadataMap = CollectionEntry<'site'>['data']['sections'];
 type SiteSectionMetadata = SiteSectionMetadataMap[string];
-type ThemePresentation = CollectionEntry<'theme'>['data']['presentation'];
-type InlineStyles = NonNullable<NonNullable<ThemePresentation>['inlineStyles']>;
 type GalleryImage = {
 	image: string;
 	src: string;
@@ -30,20 +30,32 @@ type CardListLayout = 'image-top' | 'image-left' | 'image-right';
 type CardListFlow = 'grid' | 'stack';
 type CardListSize = 's' | 'm' | 'l' | 'xl';
 type CardListWidth = 'text' | 'narrow' | 'normal' | 'wide';
+type InlineNote = {
+	markdown: string;
+	number: number;
+	id: string;
+	referenceId: string;
+};
 type SectionContentBlock =
 	| { type: 'html'; html: string }
 	| { type: 'image-stack'; images: GalleryImage[] }
 	| { type: 'image-carousel'; images: GalleryImage[] }
-	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width: CardListWidth; cards: CardListItem[] };
+	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width: CardListWidth; cards: CardListItem[] }
+	| { type: 'note'; html: string; number?: number; id?: string; referenceId?: string };
 export type ResolvedSection = SiteSectionMetadata & {
 	id: string;
 	title: string;
+	titleHtml: string;
 	contentBlocks: SectionContentBlock[];
 };
 
+export type SectionNavigation = {
+	id: string;
+	title: string;
+};
+
 const headingRegex = /<h2\b([^>]*)>([\s\S]*?)<\/h2>/gi;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
-const inlineStyleReferenceRegex = /\[([^\]<]+)\]\{\.([a-z][a-z0-9-]*)\}/g;
 const markdownH2Regex = /^##\s+.*$/gm;
 const imageProvenanceCommentRegex = /<!--\s*norna-image-provenance:[\s\S]*?-->/gi;
 
@@ -84,25 +96,141 @@ const getExplicitHeadingId = (headingHtml: string) =>
 const getHeadingTitle = (headingHtml: string) =>
 	decodeHtmlEntities(stripTags(headingHtml)).replace(explicitHeadingIdRegex, '').trim();
 
-const applyInlineStyles = (html: string, inlineStyles: InlineStyles | undefined) =>
-	html.replace(inlineStyleReferenceRegex, (_match, text: string, styleName: string) => {
-		const style = inlineStyles?.[styleName];
+const getHeadingTitleHtml = (headingHtml: string) =>
+	prepareContentHtml(headingHtml.replace(explicitHeadingIdRegex, '').trim());
 
-		if (!style) {
-			throw new Error(`Markdown uses inline style ".${styleName}", but theme.md presentation.inlineStyles.${styleName} is not defined.`);
+export const getSectionNavigation = (html: string, sectionMetadata: SiteSectionMetadataMap): SectionNavigation[] => {
+	const matches = Array.from(html.matchAll(headingRegex));
+	const sectionIds = new Set<string>();
+	const sections = matches.map((match) => {
+		const attributes = match[1] ?? '';
+		const headingHtml = match[2] ?? '';
+		const explicitId = getExplicitHeadingId(headingHtml);
+		const id = getHeadingId(attributes, headingHtml);
+		const title = getHeadingTitle(headingHtml);
+
+		if (!explicitId) {
+			throw new Error(`Section heading "${title}" is missing an explicit id. Write it as: ## ${title} {#${id}}`);
 		}
 
-		return `<span class="inline-style inline-style-${styleName}" style="--inline-style-color: ${style.color}">${text}</span>`;
+		if (sectionIds.has(id)) {
+			throw new Error(`Duplicate Markdown section heading id: ${id}`);
+		}
+
+		sectionIds.add(id);
+		return { id, title };
 	});
 
+	for (const id of Object.keys(sectionMetadata)) {
+		if (!sectionIds.has(id)) {
+			throw new Error(
+				`Section metadata "${id}" does not match any Markdown section. Add "## Heading {#${id}}" or remove sections.${id}.`,
+			);
+		}
+	}
+
+	return sections;
+};
+
 const stripImageProvenanceComments = (html: string) => html.replace(imageProvenanceCommentRegex, '');
 
-const prepareContentHtml = (html: string, inlineStyles: InlineStyles | undefined) =>
+const prepareContentHtml = (html: string) =>
 	applyBasePathToHtml(
 		projectConfig.site.basePath,
-		stripImageProvenanceComments(applyInlineStyles(html, inlineStyles)),
+		stripImageProvenanceComments(html),
 	);
 
+const htmlVoidElements = new Set([
+	'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link',
+	'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+// Keep notes aligned with the Markdown block immediately before them instead of
+// aligning them with a whole run of paragraphs rendered as one HTML fragment.
+const splitHtmlIntoBlocks = (html: string) => {
+	const tagRegex = /<!--[\s\S]*?-->|<\/?([a-z][\w:-]*)(?:\s[^<>]*?)?\/?>/gi;
+	const blocks: string[] = [];
+	let blockStart = -1;
+	let depth = 0;
+	let cursor = 0;
+
+	for (const match of html.matchAll(tagRegex)) {
+		const start = match.index ?? 0;
+		const token = match[0] ?? '';
+		const tagName = match[1]?.toLowerCase();
+		if (!tagName) continue;
+
+		const isClosing = /^<\//.test(token);
+		const isSelfClosing = /\/\s*>$/.test(token) || htmlVoidElements.has(tagName);
+
+		if (isClosing) {
+			if (depth > 0) depth -= 1;
+			if (depth === 0 && blockStart >= 0) {
+				blocks.push(html.slice(blockStart, start + token.length));
+				cursor = start + token.length;
+				blockStart = -1;
+			}
+			continue;
+		}
+
+		if (depth === 0) {
+			if (blockStart < 0) blockStart = start;
+			if (isSelfClosing) {
+				blocks.push(html.slice(blockStart, start + token.length));
+				cursor = start + token.length;
+				blockStart = -1;
+			}
+		}
+
+		if (!isSelfClosing) depth += 1;
+	}
+
+	if (blockStart >= 0) {
+		blocks.push(html.slice(blockStart).trim());
+		cursor = html.length;
+	}
+
+	const prefix = html.slice(0, blocks.length > 0 ? html.indexOf(blocks[0]!) : html.length).trim();
+	const suffix = html.slice(cursor).trim();
+	return [prefix, ...blocks, suffix].filter(Boolean);
+};
+
+const inlineNoteMarkerRegex = /^\s*<norna-inline-note\s+data-note-index="(\d+)"\s*><\/norna-inline-note>\s*$/i;
+const noteDeclarationParagraphRegex = /<p>\s*\{note:\s*[\s\S]*?\}\s*<\/p>/gi;
+const htmlCodeRegionRegex = /<pre\b[\s\S]*?<\/pre>|<code\b[\s\S]*?<\/code>/gi;
+
+const replaceHtmlOutsideCode = (html: string, transform: (value: string) => string) => {
+	let result = '';
+	let cursor = 0;
+
+	for (const match of html.matchAll(htmlCodeRegionRegex)) {
+		const start = match.index ?? 0;
+		result += transform(html.slice(cursor, start));
+		result += match[0];
+		cursor = start + match[0].length;
+	}
+
+	return result + transform(html.slice(cursor));
+};
+
+const applyInlineNoteMarkup = (html: string, notes: InlineNote[]) => {
+	let referenceIndex = 0;
+	const withReferences = replaceHtmlOutsideCode(html, (value) => value.replace(/\{note-ref\}/g, () => {
+		const note = notes[referenceIndex];
+		if (!note) return '{note-ref}';
+
+		referenceIndex += 1;
+		return `\u2060<sup class="section-note-ref"><a id="${note.referenceId}" href="#${note.id}" aria-label="Note ${note.number}" aria-describedby="${note.id}" data-note-id="${note.id}">${note.number}</a></sup>`;
+	}));
+
+	let noteIndex = 0;
+	return withReferences.replace(noteDeclarationParagraphRegex, () => {
+		const marker = `<norna-inline-note data-note-index="${noteIndex}"></norna-inline-note>`;
+		noteIndex += 1;
+		return marker;
+	});
+};
+
 const getRawMarkdownSections = (markdown: string) => {
 	const matches = Array.from(markdown.matchAll(markdownH2Regex));
 	const sections = new Map<string, string>();
@@ -128,61 +256,103 @@ const getImageSourceKey = (page: SitePage, sectionId: string, image: string) =>
 		: `images/${sectionId}/${image}`
 );
 
-const resolveContentBlocks = (
+const renderInlineNoteMarkdown = async (markdown: string) => {
+	const result = await markdownToHtml(markdown, {
+		features: {
+			gfm: true,
+			smartPunctuation: true,
+		},
+	});
+
+	if (/<img\b/i.test(result.html)) {
+		throw new Error('Inline notes cannot contain images. Use a Norna image block with a caption instead.');
+	}
+
+	return prepareContentHtml(result.html);
+};
+
+const resolveContentBlocks = async (
 	html: string,
 	rawMarkdown: string,
 	page: SitePage,
 	sectionId: string,
-	inlineStyles: InlineStyles | undefined,
+	inlineNotes: InlineNote[] = [],
 ) => {
 	const rawBlocks = extractNornaMarkdownBlocks(rawMarkdown);
+	const renderedHtml = applyInlineNoteMarkup(html, inlineNotes);
 	const splitBlocks = rawBlocks.length > 0
-		? splitNornaRenderedCodeBlocks(html, rawBlocks)
-		: splitNornaMarkdownBlockMarkers(html);
+		? splitNornaRenderedCodeBlocks(renderedHtml, rawBlocks)
+		: splitNornaMarkdownBlockMarkers(renderedHtml);
+	const hasNotes = inlineNotes.length > 0;
+	const contentBlocks = hasNotes
+		? splitBlocks.flatMap((block) => block.type === 'html'
+			? splitHtmlIntoBlocks(block.html).map((htmlBlock) => ({ type: 'html' as const, html: htmlBlock }))
+			: [block])
+		: splitBlocks;
+	const resolvedBlocks: SectionContentBlock[] = [];
 
-	return splitBlocks.map((block): SectionContentBlock => {
+	for (const block of contentBlocks) {
 		if (block.type === 'html') {
-			return {
-				type: 'html',
-				html: prepareContentHtml(block.html, inlineStyles),
-			};
+			const inlineNoteMarker = block.html.match(inlineNoteMarkerRegex);
+			if (inlineNoteMarker) {
+				const note = inlineNotes[Number(inlineNoteMarker[1])];
+				if (!note) {
+					throw new Error('Norna inline note markup could not be matched to its note text.');
+				}
+
+				resolvedBlocks.push({
+					type: 'note',
+					html: await renderInlineNoteMarkdown(note.markdown),
+					number: note.number,
+					id: note.id,
+					referenceId: note.referenceId,
+				});
+				continue;
+			}
+
+			resolvedBlocks.push({ type: 'html', html: prepareContentHtml(block.html) });
+			continue;
+		}
+
+		if (block.type === 'card-list') {
+			resolvedBlocks.push({
+				type: 'card-list',
+				layout: block.layout,
+				flow: block.flow,
+				size: block.size,
+				width: block.width,
+				cards: block.cards.map((card: CardListItem) => ({
+					...card,
+					...(card.image ? { src: getImageSourceKey(page, sectionId, card.image) } : {}),
+				})),
+			});
+			continue;
 		}
 
-		return {
+		resolvedBlocks.push({
 			type: block.type,
-			...(block.type === 'card-list'
-				? {
-					layout: block.layout,
-					flow: block.flow,
-					size: block.size,
-					width: block.width,
-					cards: block.cards.map((card: CardListItem) => ({
-						...card,
-						...(card.image ? { src: getImageSourceKey(page, sectionId, card.image) } : {}),
-					})),
-				}
-				: {
-					images: block.images.map((image: { image: string; alt?: string; caption?: string }) => ({
-						...image,
-						src: getImageSourceKey(page, sectionId, image.image),
-					})),
-				}),
-		};
-	});
+			images: block.images.map((image: { image: string; alt?: string; caption?: string }) => ({
+				...image,
+				src: getImageSourceKey(page, sectionId, image.image),
+			})),
+		});
+	}
+
+	return resolvedBlocks;
 };
 
-export const getSectionsContent = (
+export const getSectionsContent = async (
 	html: string,
 	rawMarkdown: string,
 	sectionMetadata: SiteSectionMetadataMap,
 	page: SitePage,
-	inlineStyles?: InlineStyles,
 ) => {
 	const matches = Array.from(html.matchAll(headingRegex));
 	const rawSections = getRawMarkdownSections(rawMarkdown);
 	const metadataIds = new Set(Object.keys(sectionMetadata));
 	const sections: ResolvedSection[] = [];
 	const sectionIds = new Set<string>();
+	let nextNoteNumber = 1;
 
 	for (let index = 0; index < matches.length; index += 1) {
 		const match = matches[index];
@@ -205,11 +375,33 @@ export const getSectionsContent = (
 		}
 
 		sectionIds.add(id);
+		const rawSection = rawSections.get(id) ?? '';
+		const inlineNoteDiagnostics = extractInlineNoteDiagnostics(rawSection, {
+			label: 'Markdown section',
+		});
+		if (inlineNoteDiagnostics.errors.length > 0) {
+			throw new Error(inlineNoteDiagnostics.errors[0].message);
+		}
+
+		const inlineNotes = inlineNoteDiagnostics.notes.map((note) => {
+			const number = nextNoteNumber;
+			nextNoteNumber += 1;
+			const pageKey = page.routeId || 'home';
+			const noteKey = `${pageKey}-${id}-${number}`;
+			return {
+				...note,
+				number,
+				id: `note-${noteKey}`,
+				referenceId: `note-ref-${noteKey}`,
+			};
+		});
+
 		sections.push({
 			...(sectionMetadata[id] ?? {}),
 			id,
 			title,
-			contentBlocks: resolveContentBlocks(content, rawSections.get(id) ?? '', page, id, inlineStyles),
+			titleHtml: getHeadingTitleHtml(headingHtml),
+			contentBlocks: await resolveContentBlocks(content, rawSection, page, id, inlineNotes),
 		});
 	}
 

package/src/lib/sitePublicAssets.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { sitePublicDir } from '../../scripts/lib/site-paths.mjs';
 import projectConfig from '../../scripts/lib/project-config.mjs';
+export { getLogoAsset } from '../../scripts/lib/logo-assets.mjs';
 import { withBasePath } from './basePath';
 
 type IconLink = {