@janga/norna 0.7.0

package/src/components/SiteSection.astro

@@ -0,0 +1,174 @@
+---
+import type { CollectionEntry } from 'astro:content';
+import { resolveTypographyOverride } from '../../scripts/lib/typography.mjs';
+import GalleryGrid from './GalleryGrid.astro';
+
+type SiteSection = CollectionEntry<'site'>['data']['sections'][number];
+type ResolvedSection = SiteSection & { title: string; contentHtml: string };
+type ResponsiveValue<T> = { desktop: T; mobile: T };
+type ResponsiveOverride<T> = { desktop?: T; mobile?: T };
+type TextAlign = 'left' | 'center' | 'right';
+type TextSize = 'small' | 'medium' | 'large' | 'xlarge';
+type SectionPresentationOverride = {
+	backgroundColor?: string;
+	textColor?: string;
+	typography?: NonNullable<SiteSection['presentation']>['typography'];
+};
+type ResolvedPagePresentation = {
+	backgroundColor: string;
+	textColor: string;
+	typography: {
+		preset: string;
+		values: any;
+	};
+};
+
+interface Props {
+	section: ResolvedSection;
+	pagePresentation: ResolvedPagePresentation;
+	headingLevel: 1 | 2;
+	priorityGalleryImage?: boolean;
+}
+
+const { section, pagePresentation, headingLevel, priorityGalleryImage = false } = Astro.props;
+const HeadingTag = headingLevel === 1 ? 'h1' : 'h2';
+const headingSizeValues: Record<TextSize, ResponsiveValue<string>> = {
+	small: {
+		desktop: 'clamp(1.15rem, 2.2vw, 2rem)',
+		mobile: 'clamp(1.15rem, 5vw, 1.8rem)',
+	},
+	medium: {
+		desktop: 'clamp(1.4rem, 3.1vw, 3.2rem)',
+		mobile: 'clamp(1.4rem, 3.1vw, 3.2rem)',
+	},
+	large: {
+		desktop: 'clamp(1.65rem, 4.6vw, 5.65rem)',
+		mobile: 'clamp(1.9rem, 8vw, 3.2rem)',
+	},
+	xlarge: {
+		desktop: 'clamp(2rem, 5.6vw, 7rem)',
+		mobile: 'clamp(2.15rem, 9.4vw, 3.8rem)',
+	},
+};
+const bodySizeValues: Record<TextSize, ResponsiveValue<string>> = {
+	small: {
+		desktop: 'clamp(0.9rem, 0.86rem + 0.16vw, 1rem)',
+		mobile: 'clamp(0.9rem, 0.86rem + 0.16vw, 1rem)',
+	},
+	medium: {
+		desktop: 'clamp(1rem, 0.96rem + 0.18vw, 1.125rem)',
+		mobile: 'clamp(1rem, 0.96rem + 0.18vw, 1.125rem)',
+	},
+	large: {
+		desktop: 'clamp(1.1rem, 1.04rem + 0.24vw, 1.25rem)',
+		mobile: 'clamp(1.1rem, 1.04rem + 0.24vw, 1.25rem)',
+	},
+	xlarge: {
+		desktop: 'clamp(1.18rem, 1.08rem + 0.36vw, 1.42rem)',
+		mobile: 'clamp(1.18rem, 1.08rem + 0.36vw, 1.42rem)',
+	},
+};
+const captionSizeValues: Record<TextSize, ResponsiveValue<string>> = {
+	small: {
+		desktop: 'clamp(0.82rem, 0.78rem + 0.12vw, 0.92rem)',
+		mobile: 'clamp(0.82rem, 0.78rem + 0.12vw, 0.92rem)',
+	},
+	medium: {
+		desktop: 'clamp(0.9rem, 0.86rem + 0.16vw, 1rem)',
+		mobile: 'clamp(0.9rem, 0.86rem + 0.16vw, 1rem)',
+	},
+	large: {
+		desktop: 'clamp(1rem, 0.94rem + 0.2vw, 1.12rem)',
+		mobile: 'clamp(1rem, 0.94rem + 0.2vw, 1.12rem)',
+	},
+	xlarge: {
+		desktop: 'clamp(1.08rem, 1rem + 0.28vw, 1.25rem)',
+		mobile: 'clamp(1.08rem, 1rem + 0.28vw, 1.25rem)',
+	},
+};
+const sectionOverride = section.presentation as SectionPresentationOverride | undefined;
+const getSizeValue = (
+	sizeValues: Record<TextSize, ResponsiveValue<string>>,
+	size: TextSize,
+) => sizeValues[size];
+const backgroundColor = sectionOverride?.backgroundColor
+	?? pagePresentation.backgroundColor;
+const textColor = sectionOverride?.textColor
+	?? pagePresentation.textColor;
+const resolvedTypography = resolveTypographyOverride(pagePresentation.typography, sectionOverride?.typography);
+const typography = resolvedTypography.values;
+const headingAlign = typography.heading.align as ResponsiveValue<TextAlign>;
+const bodyAlign = typography.body.align as ResponsiveValue<TextAlign>;
+const captionAlign = typography.caption.align as ResponsiveValue<TextAlign>;
+const headingFontSize = getSizeValue(headingSizeValues, typography.heading.size as TextSize);
+const bodyFontSize = getSizeValue(bodySizeValues, typography.body.size as TextSize);
+const captionFontSize = getSizeValue(captionSizeValues, typography.caption.size as TextSize);
+const justifyByAlign: Record<TextAlign, string> = {
+	left: 'flex-start',
+	center: 'center',
+	right: 'flex-end',
+};
+const getAlignedTextWidth = (
+	align: ResponsiveValue<TextAlign>,
+	centeredWidth: string,
+): ResponsiveValue<string> => ({
+	desktop: align.desktop === 'center' ? centeredWidth : 'var(--gallery-layout-width)',
+	mobile: align.mobile === 'center' ? centeredWidth : 'var(--gallery-layout-width)',
+});
+const headingWidth = getAlignedTextWidth(headingAlign, '760px');
+const bodyWidth = getAlignedTextWidth(bodyAlign, 'var(--text-width)');
+const hasGallery = section.gallery.length > 0;
+const sectionStyle = [
+	`--section-background-color: ${backgroundColor}`,
+	`--section-text-color: ${textColor}`,
+	`--section-heading-align-desktop: ${headingAlign.desktop}`,
+	`--section-heading-align-mobile: ${headingAlign.mobile}`,
+	`--section-heading-font-size-desktop: ${headingFontSize.desktop}`,
+	`--section-heading-font-size-mobile: ${headingFontSize.mobile}`,
+	`--section-heading-line-height: ${typography.heading.lineHeight}`,
+	`--section-heading-spacing: ${typography.heading.spacing}`,
+	`--section-heading-width-desktop: ${headingWidth.desktop}`,
+	`--section-heading-width-mobile: ${headingWidth.mobile}`,
+	`--section-body-align-desktop: ${bodyAlign.desktop}`,
+	`--section-body-align-mobile: ${bodyAlign.mobile}`,
+	`--section-body-font-size-desktop: ${bodyFontSize.desktop}`,
+	`--section-body-font-size-mobile: ${bodyFontSize.mobile}`,
+	`--section-body-line-height: ${typography.body.lineHeight}`,
+	`--section-body-paragraph-spacing: ${typography.body.paragraphSpacing}`,
+	`--section-body-width-desktop: ${bodyWidth.desktop}`,
+	`--section-body-width-mobile: ${bodyWidth.mobile}`,
+	`--section-caption-align-desktop: ${captionAlign.desktop}`,
+	`--section-caption-align-mobile: ${captionAlign.mobile}`,
+	`--section-caption-font-size-desktop: ${captionFontSize.desktop}`,
+	`--section-caption-font-size-mobile: ${captionFontSize.mobile}`,
+	`--section-caption-line-height: ${typography.caption.lineHeight}`,
+	`--section-caption-spacing: ${typography.caption.spacing}`,
+	`--section-caption-justify-desktop: ${justifyByAlign[captionAlign.desktop]}`,
+	`--section-caption-justify-mobile: ${justifyByAlign[captionAlign.mobile]}`,
+].join('; ');
+---
+
+<section
+	id={section.id}
+	class:list={['site-section', { 'site-section-primary': headingLevel === 1 }]}
+	data-section-title={section.title}
+	style={sectionStyle}
+>
+	<div class="section-card">
+		<header class="section-header">
+			<HeadingTag>{section.title}</HeadingTag>
+		</header>
+
+		<div class:list={['section-body', { 'section-body-has-gallery': hasGallery, 'section-body-text-only': !hasGallery }]}>
+			{section.contentHtml && <div class="section-markdown" set:html={section.contentHtml} />}
+
+			{hasGallery && (
+				<GalleryGrid
+					title={section.title}
+					items={section.gallery}
+					priorityFirstImage={priorityGalleryImage}
+				/>
+			)}
+		</div>
+	</div>
+</section>

package/src/content.config.ts

@@ -0,0 +1,171 @@
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { pathToFileURL } from 'node:url';
+import { z } from 'astro/zod';
+import { siteDir, siteDirLabel } from '../scripts/lib/site-paths.mjs';
+import { isDateOnly } from './lib/visibility';
+
+const siteEntryId = `${siteDirLabel
+	.replace(/^[./\\]+/, '')
+	.replace(/[^a-zA-Z0-9-]+/g, '-')
+	.replace(/^-+|-+$/g, '') || 'site'}-content`;
+const contentImageName = z.string().regex(/^[a-z0-9][a-z0-9.-]*\.(jpe?g|png)$/i);
+const routeSlug = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'Use lowercase letters, numbers, and hyphens.');
+const colorValue = z.string().regex(
+	/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/,
+	'Use a hex color such as "#000000".',
+);
+const textAlign = z.enum(['left', 'center', 'right']);
+const textSize = z.enum(['small', 'medium', 'large', 'xlarge']);
+const typographyPreset = z.enum(['quiet-gallery', 'compact-gallery', 'text-forward', 'statement']);
+const lineHeight = z.number()
+	.min(1, 'Use a unitless line height of at least 1.')
+	.max(3, 'Use a unitless line height of at most 3.');
+const cssLength = z.string().regex(
+	/^(?:0|(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|ch|lh))$/,
+	'Use a CSS length such as "0", "0.8em", "1rem", or "12px".',
+);
+const inlineStyleName = z.string().regex(/^[a-z][a-z0-9-]*$/);
+const dateOnly = z.string()
+	.regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD format.')
+	.refine(isDateOnly, 'Use a real calendar date.');
+const visibilityWindow = z.object({
+	from: dateOnly.optional(),
+	until: dateOnly.optional(),
+}).strict().refine(
+	(value) => value.from !== undefined || value.until !== undefined,
+	'Specify from, until, or both.',
+).refine(
+	(value) => value.from === undefined || value.until === undefined || value.from < value.until,
+	'visible.until must be later than visible.from.',
+);
+const overrideResponsiveTextAlign = z.object({
+	desktop: textAlign.optional(),
+	mobile: textAlign.optional(),
+}).strict().refine(
+	(value) => value.desktop !== undefined || value.mobile !== undefined,
+	'Specify desktop, mobile, or both.',
+);
+const commonTextPresentationOverride = {
+	align: overrideResponsiveTextAlign.optional(),
+	size: textSize.optional(),
+	lineHeight: lineHeight.optional(),
+};
+const headingPresentationOverride = z.object({
+	...commonTextPresentationOverride,
+	spacing: cssLength.optional(),
+}).strict();
+const bodyPresentationOverride = z.object({
+	...commonTextPresentationOverride,
+	paragraphSpacing: cssLength.optional(),
+}).strict();
+const captionPresentationOverride = z.object({
+	...commonTextPresentationOverride,
+	spacing: cssLength.optional(),
+}).strict();
+const typographyOverrides = z.object({
+	heading: headingPresentationOverride.optional(),
+	body: bodyPresentationOverride.optional(),
+	caption: captionPresentationOverride.optional(),
+}).strict();
+const typography = z.object({
+	preset: typographyPreset.optional(),
+	overrides: typographyOverrides.optional(),
+}).strict().refine(
+	(value) => value.preset !== undefined || value.overrides !== undefined,
+	'Specify preset, overrides, or both.',
+);
+const sectionPresentationOverride = z.object({
+	backgroundColor: colorValue.optional(),
+	textColor: colorValue.optional(),
+	typography: typography.optional(),
+}).strict();
+const themePresentation = z.object({
+	backgroundColor: colorValue.optional(),
+	textColor: colorValue.optional(),
+	inlineStyles: z.record(inlineStyleName, z.object({
+		color: colorValue,
+	}).strict()).optional(),
+	typography: typography.optional(),
+}).strict();
+const pagePresentation = z.object({
+	backgroundColor: colorValue.optional(),
+	textColor: colorValue.optional(),
+	typography: typography.optional(),
+}).strict();
+const frameColors = z.union([
+	z.enum(['theme', 'presentation']),
+	z.object({
+		backgroundColor: colorValue,
+		textColor: colorValue,
+	}).strict(),
+]);
+const frame = z.object({
+	colors: frameColors.optional(),
+}).strict();
+const pageNavigation = z.object({
+	include: z.boolean().optional(),
+	label: z.string().optional(),
+	order: z.number().int().optional(),
+}).strict();
+
+const galleryImage = z.object({
+	image: contentImageName,
+	alt: z.string(),
+	caption: z.string().optional(),
+}).strict();
+const galleryCarousel = z.object({
+	carousel: z.array(galleryImage).min(2, 'A carousel must contain at least two images.'),
+}).strict();
+const galleryItem = z.union([galleryImage, galleryCarousel]);
+
+const siteSchema = z.object({
+	title: z.string(),
+	description: z.string(),
+	slug: routeSlug.optional(),
+	navigation: pageNavigation.optional(),
+	presentation: pagePresentation.optional(),
+	frame: frame.optional(),
+	sections: z.array(
+		z.object({
+			id: z.string().regex(/^[a-z0-9-]+$/),
+			visible: visibilityWindow.optional(),
+			presentation: sectionPresentationOverride.optional(),
+			gallery: z.array(galleryItem).optional().default([]),
+		}).strict(),
+	).min(1),
+});
+
+const themeSchema = z.object({
+	presentation: themePresentation.optional(),
+	frame: frame.optional(),
+}).strict();
+
+const site = defineCollection({
+	loader: glob({
+		pattern: ['content.md', 'routes/*/route-content.md'],
+		base: pathToFileURL(siteDir),
+		generateId: ({ entry }) => {
+			if (entry === 'content.md') {
+				return siteEntryId;
+			}
+
+			const routeFolder = entry.match(/^routes\/([^/]+)\/route-content\.md$/)?.[1];
+			return routeFolder
+				? `${siteEntryId.replace(/-content$/, '')}-route-${routeFolder}`
+				: entry.replace(/[^a-zA-Z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+		},
+	}),
+	schema: siteSchema,
+});
+
+const theme = defineCollection({
+	loader: glob({
+		pattern: 'theme.md',
+		base: pathToFileURL(siteDir),
+		generateId: () => `${siteEntryId.replace(/-content$/, '')}-theme`,
+	}),
+	schema: themeSchema,
+});
+
+export const collections = { site, theme };

package/src/layouts/BaseLayout.astro

@@ -0,0 +1,90 @@
+---
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { getIconLinks } from '../lib/sitePublicAssets';
+import '../styles/global.css';
+
+type FrameColors = {
+	backgroundColor: string;
+	textColor: string;
+};
+
+interface Props {
+	title?: string;
+	description?: string;
+	frameColors: FrameColors;
+	pathname?: string;
+}
+
+const {
+	title = 'norna',
+	description = 'A norna site.',
+	frameColors,
+	pathname = '/',
+} = Astro.props;
+
+const documentTitle = title;
+const canonicalUrl = new URL(pathname, projectConfig.site.url).href;
+const iconLinks = getIconLinks();
+const scrollBehavior = projectConfig.navigation.smoothScroll.enabled ? 'smooth' : 'auto';
+const formatPercent = (value: number) => `${value}%`;
+const formatViewportHeightPercent = (value: number) => `${value}svh`;
+const documentStyle = [
+	`scroll-behavior: ${scrollBehavior}`,
+	`--font-sans: ${projectConfig.typography.fontFamily}`,
+	`--page-width: ${projectConfig.layout.pageWidth}`,
+	`--content-gutter-desktop: ${projectConfig.layout.gutter.desktop}`,
+	`--content-gutter-mobile: ${projectConfig.layout.gutter.mobile}`,
+	`--gallery-width: ${projectConfig.gallery.width}`,
+	`--gallery-max-available-width-desktop: ${formatPercent(projectConfig.gallery.maxAvailableWidthPercent.desktop)}`,
+	`--gallery-max-available-width-mobile: ${formatPercent(projectConfig.gallery.maxAvailableWidthPercent.mobile)}`,
+	`--gallery-max-image-height-desktop: ${formatViewportHeightPercent(projectConfig.gallery.maxAvailableHeightPercent.desktop)}`,
+	`--gallery-max-image-height-mobile: ${formatViewportHeightPercent(projectConfig.gallery.maxAvailableHeightPercent.mobile)}`,
+].join('; ');
+const { buildInfo, copyrightMessage } = projectConfig.footer;
+const showBuildInfo = Boolean(buildInfo?.enabled);
+const buildTime = showBuildInfo
+	? new Intl.DateTimeFormat(buildInfo.dateTimeFormat.locale, {
+		dateStyle: buildInfo.dateTimeFormat.dateStyle,
+		timeStyle: buildInfo.dateTimeFormat.timeStyle,
+		timeZone: buildInfo.dateTimeFormat.timeZone,
+	}).format(new Date())
+	: null;
+const showFooter = Boolean(copyrightMessage || showBuildInfo);
+const footerStyle = [
+	`--site-footer-background-color: ${frameColors.backgroundColor}`,
+	`--site-footer-text-color: ${frameColors.textColor}`,
+].join('; ');
+---
+
+<!doctype html>
+<html lang={projectConfig.locale.lang} style={documentStyle}>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="format-detection" content="telephone=no" />
+		<meta name="description" content={description} />
+		<meta name="theme-color" content="#000000" />
+		<link rel="canonical" href={canonicalUrl} />
+		<meta name="generator" content={Astro.generator} />
+		{iconLinks.map((iconLink) => (
+			<link
+				rel={iconLink.rel}
+				type={iconLink.type}
+				sizes={iconLink.sizes}
+				href={iconLink.href}
+			/>
+		))}
+		<title>{documentTitle}</title>
+	</head>
+	<body>
+		<slot />
+		{showFooter && (
+			<footer class="site-footer" style={footerStyle}>
+				<p>
+					{copyrightMessage}
+					{showBuildInfo && <span>{buildInfo.text} {buildTime}</span>}
+				</p>
+			</footer>
+		)}
+	</body>
+</html>

package/src/lib/generatedImages.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { generatedImagesManifestPath } from '../../scripts/lib/site-paths.mjs';
+
+type GeneratedImage = {
+	outputVersion?: number;
+	sourceHash?: string;
+	width: number;
+	height: number;
+	variants: Array<{
+		src: string;
+		width: number;
+	}>;
+};
+
+const readGeneratedImages = () => {
+	try {
+		return JSON.parse(readFileSync(generatedImagesManifestPath, 'utf8')) as Record<string, GeneratedImage | undefined>;
+	} catch {
+		return {};
+	}
+};
+
+const images = readGeneratedImages();
+const maxDisplayImageWidth = 1920;
+const fallbackDisplayImageWidth = 1440;
+
+export const getGeneratedImage = (src: string) => images[src];
+
+export const getLinkedImageSrc = (src: string) => getGeneratedImage(src)?.variants.at(-1)?.src ?? src;
+
+const getDisplayVariants = (variants: GeneratedImage['variants']) => {
+	const sortedVariants = [...variants].sort((a, b) => a.width - b.width);
+	const displayVariants = sortedVariants.filter((variant) => variant.width <= maxDisplayImageWidth);
+
+	return displayVariants.length > 0 ? displayVariants : sortedVariants;
+};
+
+const getFallbackVariant = (variants: GeneratedImage['variants']) => (
+	variants.filter((variant) => variant.width <= fallbackDisplayImageWidth).at(-1) ?? variants[0]
+);
+
+export const getImageAttributes = (src: string, sizes: string) => {
+	const image = getGeneratedImage(src);
+
+	if (!image) {
+		return {
+			src,
+			sizes,
+		};
+	}
+
+	const displayVariants = getDisplayVariants(image.variants);
+	const fallbackVariant = getFallbackVariant(displayVariants);
+
+	return {
+		src: fallbackVariant?.src ?? src,
+		srcset: displayVariants.map((variant) => `${variant.src} ${variant.width}w`).join(', '),
+		sizes,
+		style: `aspect-ratio: ${image.width} / ${image.height};`,
+		width: image.width,
+		height: image.height,
+	};
+};

package/src/lib/sectionContent.ts

@@ -0,0 +1,125 @@
+import type { CollectionEntry } from 'astro:content';
+
+type SiteSection = CollectionEntry<'site'>['data']['sections'][number];
+type ThemePresentation = CollectionEntry<'theme'>['data']['presentation'];
+type InlineStyles = NonNullable<NonNullable<ThemePresentation>['inlineStyles']>;
+
+const headingRegex = /<h2\b([^>]*)>([\s\S]*?)<\/h2>/gi;
+const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
+const inlineStyleReferenceRegex = /\[([^\]<]+)\]\{\.([a-z][a-z0-9-]*)\}/g;
+
+const stripTags = (html: string) => html.replace(/<[^>]*>/g, '');
+
+const decodeHtmlEntities = (value: string) =>
+	value
+		.replace(/&amp;/g, '&')
+		.replace(/&lt;/g, '<')
+		.replace(/&gt;/g, '>')
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'");
+
+const slugify = (value: string) =>
+	decodeHtmlEntities(stripTags(value))
+		.trim()
+		.toLowerCase()
+		.normalize('NFD')
+		.replace(/[\u0300-\u036f]/g, '')
+		.replace(/å/g, 'a')
+		.replace(/ä/g, 'a')
+		.replace(/ö/g, 'o')
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+
+const getHeadingId = (attributes: string, headingHtml: string) => {
+	const headingText = decodeHtmlEntities(stripTags(headingHtml)).trim();
+	const explicitId = headingText.match(explicitHeadingIdRegex)?.[1];
+	if (explicitId) return explicitId;
+
+	const id = attributes.match(/\sid=(["'])(.*?)\1/i)?.[2];
+	return id ? decodeHtmlEntities(id) : slugify(headingHtml);
+};
+
+const getExplicitHeadingId = (headingHtml: string) =>
+	decodeHtmlEntities(stripTags(headingHtml)).trim().match(explicitHeadingIdRegex)?.[1];
+
+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];
+
+		if (!style) {
+			throw new Error(`Markdown uses inline style ".${styleName}", but theme.md presentation.inlineStyles.${styleName} is not defined.`);
+		}
+
+		return `<span class="inline-style inline-style-${styleName}" style="--inline-style-color: ${style.color}">${text}</span>`;
+	});
+
+export const getSectionsContent = (
+	html: string,
+	sections: SiteSection[],
+	inlineStyles?: InlineStyles,
+) => {
+	const matches = Array.from(html.matchAll(headingRegex));
+	const contentById = new Map<string, { title: string; contentHtml: string }>();
+	const sectionIds = new Set(sections.map((section) => section.id));
+	const markdownSectionIds: string[] = [];
+
+	for (let index = 0; index < matches.length; index += 1) {
+		const match = matches[index];
+		const attributes = match[1] ?? '';
+		const headingHtml = match[2] ?? '';
+		const explicitId = getExplicitHeadingId(headingHtml);
+		const id = getHeadingId(attributes, headingHtml);
+		const contentStart = (match.index ?? 0) + match[0].length;
+		const nextMatch = matches[index + 1];
+		const contentEnd = nextMatch?.index ?? html.length;
+		const content = html.slice(contentStart, contentEnd).trim();
+		const title = getHeadingTitle(headingHtml);
+
+		if (!explicitId) {
+			console.warn(`Markdown section is missing an explicit heading id: "${title}". Write for example "## ${title} {#${id}}".`);
+		}
+
+		if (contentById.has(id)) {
+			throw new Error(`Duplicate Markdown section heading id: ${id}`);
+		}
+
+		contentById.set(id, {
+			title,
+			contentHtml: applyInlineStyles(content, inlineStyles),
+		});
+		markdownSectionIds.push(id);
+	}
+
+	for (const id of contentById.keys()) {
+		if (!sectionIds.has(id)) {
+			console.warn(`Markdown section exists but is not used in frontmatter: ${id}`);
+		}
+	}
+
+	const orderedMarkdownSectionIds = markdownSectionIds.filter((id) => sectionIds.has(id));
+	const frontmatterSectionIds = sections.map((section) => section.id);
+	const hasOrderMismatch = frontmatterSectionIds.some((id, index) => id !== orderedMarkdownSectionIds[index]);
+
+	if (hasOrderMismatch) {
+		console.warn('Markdown section order differs from frontmatter. Run npm run content:sync to sort Markdown according to frontmatter.');
+	}
+
+	return sections.map((section) => {
+		const content = contentById.get(section.id);
+
+		if (!content) {
+			throw new Error(
+				`Cannot find heading for "${section.id}". Each frontmatter section must have a matching level 2 Markdown heading, for example: ## Heading {#${section.id}}`,
+			);
+		}
+
+		return {
+			...section,
+			title: content.title,
+			contentHtml: content.contentHtml,
+		};
+	});
+};