getfilepress 0.0.0 → 0.1.0

package/packages/core/src/lib/content/content.ts

@@ -0,0 +1,193 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import type { PostMeta, PostSource, RenderedPost } from './types';
+import { assertUniqueSlugs, ContentError, normalizeTag, parsePost } from './parse';
+import { renderMarkdown } from './markdown';
+
+export interface ContentApi {
+	loadPostSources(): PostSource[];
+	/** Production truth: non-draft, date ≤ today. Feeds and sitemap use this. */
+	getPublishedPosts(): PostMeta[];
+	/**
+	 * What the index / tags / topics show. Same as published in production;
+	 * includes drafts under `pnpm dev` (or `FILEPRESS_SHOW_DRAFTS=1`).
+	 */
+	getListedPosts(): PostMeta[];
+	listsDrafts(): boolean;
+	getIndexPage(
+		page: number,
+		perPage: number
+	): { featured: PostMeta | null; posts: PostMeta[]; page: number; totalPages: number };
+	getIndexPageCount(perPage: number): number;
+	getBuildableSlugs(): string[];
+	getRenderedPost(slug: string): Promise<RenderedPost | null>;
+	getAllTags(): { tag: string; count: number }[];
+	getPostsByTag(tag: string): PostMeta[];
+	getAdjacentPosts(slug: string): { older: PostMeta | null; newer: PostMeta | null };
+}
+
+export interface CreateContentOptions {
+	contentDir: string;
+	/** Override draft listing. Default: on in Vite DEV, or when FILEPRESS_SHOW_DRAFTS is 1/true. */
+	listDrafts?: boolean;
+}
+
+/**
+ * Whether listings should include `draft: true` posts. Production builds stay
+ * closed unless FILEPRESS_SHOW_DRAFTS forces them open (rare; mainly for checks).
+ */
+export function resolveListDrafts(override?: boolean): boolean {
+	if (override !== undefined) return override;
+	const env = process.env.FILEPRESS_SHOW_DRAFTS?.trim();
+	if (env === '1' || env === 'true') return true;
+	if (env === '0' || env === 'false') return false;
+	return Boolean(import.meta.env.DEV);
+}
+
+/**
+ * Build a content API bound to one content directory. This is the seam a site
+ * wires up in a server-only module: `createContent({ contentDir: 'posts' })`.
+ *
+ * Reads the filesystem, so it must only be imported from server code
+ * (`+page.server.ts`, `+server.ts`, or a `*.server.ts` lib module). The pure
+ * parsing/validation logic lives in `parse.ts` and is safe to import anywhere.
+ */
+export function createContent(opts: CreateContentOptions): ContentApi {
+	const dir = isAbsolute(opts.contentDir)
+		? opts.contentDir
+		: resolve(process.cwd(), opts.contentDir);
+	const listDrafts = resolveListDrafts(opts.listDrafts);
+
+	// One prerender pass per build, so cache parsed posts in production; re-read
+	// each time in dev so edits show on refresh.
+	let cache: PostSource[] | null = null;
+
+	function loadPostSources(): PostSource[] {
+		if (cache && import.meta.env.PROD) return cache;
+
+		let filenames: string[];
+		try {
+			filenames = readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+		} catch (e: unknown) {
+			const detail = e instanceof Error ? e.message : String(e);
+			throw new ContentError(`Could not read content directory "${dir}": ${detail}`);
+		}
+
+		const posts = filenames
+			.sort((a, b) => a.localeCompare(b))
+			.map((name) => parsePost(`/${name}`, readFileSync(join(dir, name), 'utf8')));
+
+		assertUniqueSlugs(posts);
+		cache = posts;
+		return posts;
+	}
+
+	const today = () => new Date().toISOString().slice(0, 10);
+	const isPublished = (post: PostSource, now: string) => !post.draft && post.date <= now;
+	const byDateDesc = (a: PostMeta, b: PostMeta) =>
+		a.date < b.date ? 1 : a.date > b.date ? -1 : a.slug.localeCompare(b.slug);
+	const toMeta = (post: PostSource): PostMeta => {
+		const { body: _body, ...meta } = post;
+		return meta;
+	};
+
+	function getPublishedPosts(): PostMeta[] {
+		const now = today();
+		return loadPostSources()
+			.filter((p) => isPublished(p, now))
+			.sort(byDateDesc)
+			.map(toMeta);
+	}
+
+	function getListedPosts(): PostMeta[] {
+		const now = today();
+		return loadPostSources()
+			.filter((p) => {
+				if (isPublished(p, now)) return true;
+				// Drafts show in local listings regardless of date so future-dated
+				// work-in-progress is previewable. Future *published* posts stay hidden.
+				return listDrafts && p.draft;
+			})
+			.sort(byDateDesc)
+			.map(toMeta);
+	}
+
+	function getIndexPage(page: number, perPage: number) {
+		const listed = getListedPosts();
+		const featured = listed[0] ?? null;
+		const rest = listed.slice(1);
+		const size = Math.max(1, Math.floor(perPage));
+		const totalPages = Math.max(1, Math.ceil(rest.length / size));
+		const current = Math.min(Math.max(1, Math.floor(page)), totalPages);
+		const start = (current - 1) * size;
+		return {
+			featured: current === 1 ? featured : null,
+			posts: rest.slice(start, start + size),
+			page: current,
+			totalPages
+		};
+	}
+
+	function getIndexPageCount(perPage: number): number {
+		const rest = Math.max(0, getListedPosts().length - 1);
+		return Math.max(1, Math.ceil(rest / Math.max(1, Math.floor(perPage))));
+	}
+
+	function getBuildableSlugs(): string[] {
+		const now = today();
+		return loadPostSources()
+			.filter((p) => p.draft || p.date <= now)
+			.map((p) => p.slug);
+	}
+
+	function findBuildable(slug: string): PostSource | null {
+		const now = today();
+		return loadPostSources().find((p) => p.slug === slug && (p.draft || p.date <= now)) ?? null;
+	}
+
+	async function getRenderedPost(slug: string): Promise<RenderedPost | null> {
+		const post = findBuildable(slug);
+		if (!post) return null;
+		const html = await renderMarkdown(post.body);
+		return { ...toMeta(post), html };
+	}
+
+	function getAllTags(): { tag: string; count: number }[] {
+		const counts = new Map<string, number>();
+		for (const post of getListedPosts()) {
+			for (const tag of post.tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+		}
+		return [...counts.entries()]
+			.map(([tag, count]) => ({ tag, count }))
+			.sort((a, b) => a.tag.localeCompare(b.tag));
+	}
+
+	function getPostsByTag(tag: string): PostMeta[] {
+		const normalized = normalizeTag(tag);
+		return getListedPosts().filter((p) => p.tags.includes(normalized));
+	}
+
+	function getAdjacentPosts(slug: string): { older: PostMeta | null; newer: PostMeta | null } {
+		const listed = getListedPosts();
+		const i = listed.findIndex((p) => p.slug === slug);
+		if (i === -1) return { older: null, newer: null };
+		return {
+			newer: i > 0 ? listed[i - 1] : null,
+			older: i < listed.length - 1 ? listed[i + 1] : null
+		};
+	}
+
+	return {
+		loadPostSources,
+		getPublishedPosts,
+		getListedPosts,
+		listsDrafts: () => listDrafts,
+		getIndexPage,
+		getIndexPageCount,
+		getBuildableSlugs,
+		getRenderedPost,
+		getAllTags,
+		getPostsByTag,
+		getAdjacentPosts
+	};
+}

package/packages/core/src/lib/content/feeds.ts

@@ -0,0 +1,102 @@
+import type { SiteConfig } from '../config';
+import { absoluteUrl } from '../config';
+import type { PageMeta, PostMeta } from './types';
+
+function escapeXml(value: string): string {
+	return value
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;');
+}
+
+/** RFC-822 date at midnight UTC for a YYYY-MM-DD string. */
+function rfc822(date: string): string {
+	const [y, m, d] = date.split('-').map(Number);
+	return new Date(Date.UTC(y, m - 1, d)).toUTCString();
+}
+
+/** Build an RSS 2.0 feed from published posts. */
+export function buildRssXml(site: SiteConfig, posts: PostMeta[]): string {
+	const items = posts
+		.map((post) => {
+			const url = absoluteUrl(site, `/posts/${post.slug}`);
+			return `		<item>
+			<title>${escapeXml(post.title)}</title>
+			<link>${escapeXml(url)}</link>
+			<guid isPermaLink="true">${escapeXml(url)}</guid>
+			<pubDate>${rfc822(post.date)}</pubDate>
+			${post.description ? `<description>${escapeXml(post.description)}</description>` : ''}
+			${post.tags.map((t) => `<category>${escapeXml(t)}</category>`).join('\n\t\t\t')}
+		</item>`;
+		})
+		.join('\n');
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+	<channel>
+		<title>${escapeXml(site.title)}</title>
+		<link>${escapeXml(site.url)}</link>
+		<description>${escapeXml(site.description)}</description>
+		<atom:link href="${escapeXml(absoluteUrl(site, '/rss.xml'))}" rel="self" type="application/rss+xml" />
+${items}
+	</channel>
+</rss>
+`;
+}
+
+/** Build a sitemap covering the index, static pages, paginated pages, topics, tags, and posts. */
+export function buildSitemapXml(
+	site: SiteConfig,
+	data: {
+		posts: PostMeta[];
+		tags: { tag: string }[];
+		pageCount: number;
+		/** Published static pages (`pages/*.md`). */
+		pages?: PageMeta[];
+	}
+): string {
+	const esc = (v: string) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+	const extraPages: { loc: string }[] = [];
+	for (let n = 2; n <= data.pageCount; n++) extraPages.push({ loc: absoluteUrl(site, `/page/${n}`) });
+
+	const staticPages = data.pages ?? [];
+
+	const urls: { loc: string; lastmod?: string }[] = [
+		{ loc: absoluteUrl(site, '/') },
+		...(site.homePage ? [{ loc: absoluteUrl(site, '/writing') }] : []),
+		{ loc: absoluteUrl(site, '/topics') },
+		{ loc: absoluteUrl(site, '/tags') },
+		...extraPages,
+		...staticPages.map((p) => ({ loc: absoluteUrl(site, `/${p.slug}`) })),
+		...data.posts.map((p) => ({
+			loc: absoluteUrl(site, `/posts/${p.slug}`),
+			lastmod: p.updated ?? p.date
+		})),
+		...data.tags.map(({ tag }) => ({ loc: absoluteUrl(site, `/tags/${tag}`) }))
+	];
+
+	const body = urls
+		.map(
+			({ loc, lastmod }) =>
+				`	<url><loc>${esc(loc)}</loc>${lastmod ? `<lastmod>${lastmod}</lastmod>` : ''}</url>`
+		)
+		.join('\n');
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${body}
+</urlset>
+`;
+}
+
+/** Build robots.txt referencing the sitemap. */
+export function buildRobotsTxt(site: SiteConfig): string {
+	return `User-agent: *
+Allow: /
+
+Sitemap: ${absoluteUrl(site, '/sitemap.xml')}
+`;
+}

package/packages/core/src/lib/content/markdown.ts

@@ -0,0 +1,78 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeStringify from 'rehype-stringify';
+import bash from 'highlight.js/lib/languages/bash';
+import css from 'highlight.js/lib/languages/css';
+import go from 'highlight.js/lib/languages/go';
+import javascript from 'highlight.js/lib/languages/javascript';
+import json from 'highlight.js/lib/languages/json';
+import markdown from 'highlight.js/lib/languages/markdown';
+import python from 'highlight.js/lib/languages/python';
+import rust from 'highlight.js/lib/languages/rust';
+import sql from 'highlight.js/lib/languages/sql';
+import typescript from 'highlight.js/lib/languages/typescript';
+import xml from 'highlight.js/lib/languages/xml';
+import yaml from 'highlight.js/lib/languages/yaml';
+import { rehypeFigure } from './rehype-figure';
+
+/**
+ * Markdown → HTML pipeline (build-time only).
+ *
+ * Decisions baked in here:
+ * - GFM enabled (tables, strikethrough, task lists, autolinks).
+ * - Raw HTML in post bodies is passed through (`allowDangerousHtml` + `rehype-raw`).
+ *   The content trust boundary is "whoever can push to the repo", so this is the
+ *   owner's own HTML.
+ * - Headings get stable slug ids (`rehype-slug`) plus a self-anchor link
+ *   (`rehype-autolink-headings`) so deep links work.
+ * - Code blocks are syntax-highlighted at build time with a small language
+ *   allowlist (not the full highlight.js registry).
+ * - Image-only paragraphs become `<figure>` with a `<figcaption>` from the
+ *   image title/alt (`rehype-figure`), for captioned editorial images.
+ */
+const processor = unified()
+	.use(remarkParse)
+	.use(remarkGfm)
+	.use(remarkRehype, { allowDangerousHtml: true })
+	.use(rehypeRaw)
+	.use(rehypeSlug)
+	.use(rehypeAutolinkHeadings, {
+		behavior: 'wrap',
+		properties: { className: ['heading-anchor'] }
+	})
+	.use(rehypeFigure)
+	.use(rehypeHighlight, {
+		detect: false,
+		ignoreMissing: true,
+		languages: {
+			bash,
+			css,
+			go,
+			javascript,
+			js: javascript,
+			json,
+			markdown,
+			md: markdown,
+			python,
+			rust,
+			sql,
+			typescript,
+			ts: typescript,
+			xml,
+			html: xml,
+			yaml,
+			yml: yaml
+		}
+	})
+	.use(rehypeStringify, { allowDangerousHtml: true });
+
+export async function renderMarkdown(markdown: string): Promise<string> {
+	const file = await processor.process(markdown);
+	return String(file);
+}

package/packages/core/src/lib/content/pages.ts

@@ -0,0 +1,103 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import type { PageMeta, PageSource, RenderedPage } from './types';
+import { ContentError, assertUniqueSlugs, parsePage } from './parse';
+import { renderMarkdown } from './markdown';
+import { resolveListDrafts } from './content';
+
+export interface PagesApi {
+	loadPageSources(): PageSource[];
+	/** Non-draft pages (sitemap, public nav helpers). */
+	getPublishedPages(): PageMeta[];
+	/** Listed pages: published, plus drafts under `pnpm dev`. */
+	getListedPages(): PageMeta[];
+	listsDrafts(): boolean;
+	getBuildableSlugs(): string[];
+	getRenderedPage(slug: string): Promise<RenderedPage | null>;
+}
+
+export interface CreatePagesOptions {
+	/** Absolute or cwd-relative path to `pages/`. Missing dir → empty site (ok). */
+	pagesDir: string;
+	listDrafts?: boolean;
+}
+
+/**
+ * Content API for static Markdown pages (`pages/*.md` → `/<slug>`).
+ * Absent `pages/` directory is fine — returns empty lists.
+ */
+export function createPages(opts: CreatePagesOptions): PagesApi {
+	const dir = isAbsolute(opts.pagesDir)
+		? opts.pagesDir
+		: resolve(process.cwd(), opts.pagesDir);
+	const listDrafts = resolveListDrafts(opts.listDrafts);
+
+	let cache: PageSource[] | null = null;
+
+	function loadPageSources(): PageSource[] {
+		if (cache && import.meta.env.PROD) return cache;
+
+		if (!existsSync(dir)) {
+			cache = [];
+			return cache;
+		}
+
+		let filenames: string[];
+		try {
+			filenames = readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+		} catch (e: unknown) {
+			const detail = e instanceof Error ? e.message : String(e);
+			throw new ContentError(`Could not read pages directory "${dir}": ${detail}`);
+		}
+
+		const pages = filenames
+			.sort((a, b) => a.localeCompare(b))
+			.map((name) => parsePage(`/pages/${name}`, readFileSync(join(dir, name), 'utf8')));
+
+		assertUniqueSlugs(pages);
+		cache = pages;
+		return pages;
+	}
+
+	const toMeta = (page: PageSource): PageMeta => {
+		const { body: _body, ...meta } = page;
+		return meta;
+	};
+
+	const byOrder = (a: PageMeta, b: PageMeta) =>
+		a.order !== b.order ? a.order - b.order : a.slug.localeCompare(b.slug);
+
+	function getPublishedPages(): PageMeta[] {
+		return loadPageSources()
+			.filter((p) => !p.draft)
+			.sort(byOrder)
+			.map(toMeta);
+	}
+
+	function getListedPages(): PageMeta[] {
+		return loadPageSources()
+			.filter((p) => !p.draft || listDrafts)
+			.sort(byOrder)
+			.map(toMeta);
+	}
+
+	function getBuildableSlugs(): string[] {
+		return loadPageSources().map((p) => p.slug);
+	}
+
+	async function getRenderedPage(slug: string): Promise<RenderedPage | null> {
+		const page = loadPageSources().find((p) => p.slug === slug);
+		if (!page) return null;
+		const html = await renderMarkdown(page.body);
+		return { ...toMeta(page), html };
+	}
+
+	return {
+		loadPageSources,
+		getPublishedPages,
+		getListedPages,
+		listsDrafts: () => listDrafts,
+		getBuildableSlugs,
+		getRenderedPage
+	};
+}

package/packages/core/src/lib/content/parse.ts

@@ -0,0 +1,214 @@
+import matter from 'gray-matter';
+import type { PageSource, PostSource, RawFrontmatter, RawPageFrontmatter } from './types';
+import { RESERVED_PAGE_SLUGS } from './types';
+
+/**
+ * A content error that names the offending file. The build must fail loudly and
+ * attributably (per PHASE_1_BRIEF §3 and GENESIS edge cases 1–3), never crash
+ * with a generic stack trace or silently drop a post.
+ *
+ * This module is deliberately free of `import.meta.glob` / Vite specifics so the
+ * parsing + validation logic can be unit-tested in isolation.
+ */
+export class ContentError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'ContentError';
+	}
+}
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Validate a strict YYYY-MM-DD date string and confirm it's a real calendar date. */
+export function assertValidDate(value: string, field: string, file: string): string {
+	if (!DATE_RE.test(value)) {
+		throw new ContentError(
+			`${file}: invalid \`${field}\` "${value}" — dates must be strictly YYYY-MM-DD (e.g. 2026-07-04).`
+		);
+	}
+	const [y, m, d] = value.split('-').map(Number);
+	const dt = new Date(Date.UTC(y, m - 1, d));
+	if (dt.getUTCFullYear() !== y || dt.getUTCMonth() !== m - 1 || dt.getUTCDate() !== d) {
+		throw new ContentError(`${file}: \`${field}\` "${value}" is not a real calendar date.`);
+	}
+	return value;
+}
+
+/**
+ * Derive a URL-safe slug from a string. Lowercases, trims, turns whitespace and
+ * underscores into hyphens, and drops any character that isn't a Unicode letter,
+ * number, or hyphen (emoji and punctuation are stripped; accented letters kept).
+ */
+export function slugify(input: string): string {
+	return input
+		.normalize('NFKC')
+		.toLowerCase()
+		.trim()
+		.replace(/[\s_]+/g, '-')
+		.replace(/[^\p{L}\p{N}-]+/gu, '')
+		.replace(/-{2,}/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+/** Normalize a tag: coerce to string, trim, lowercase (edge case 13). */
+export function normalizeTag(tag: unknown): string {
+	return String(tag).trim().toLowerCase();
+}
+
+/** Filename (no extension, no directory) from a "/posts/foo.md" style path. */
+export function filenameOf(path: string): string {
+	return path.slice(path.lastIndexOf('/') + 1).replace(/\.md$/, '');
+}
+
+function normalizeDateInput(value: unknown): string {
+	// YAML auto-parses unquoted dates into Date objects; a phone may also type a
+	// string. Normalize both to the YYYY-MM-DD text before strict validation.
+	return value instanceof Date ? value.toISOString().slice(0, 10) : String(value).trim();
+}
+
+/** Parse and validate one raw Markdown file into a PostSource. Throws ContentError. */
+export function parsePost(path: string, raw: string): PostSource {
+	let parsed: matter.GrayMatterFile<string>;
+	try {
+		// gray-matter tolerates trailing whitespace after the closing `---` (edge case 8).
+		parsed = matter(raw);
+	} catch (e: unknown) {
+		const detail = e instanceof Error ? e.message : String(e);
+		throw new ContentError(`${path}: could not parse YAML frontmatter — ${detail}`);
+	}
+
+	const fm = parsed.data as RawFrontmatter;
+
+	if (fm.title === undefined || fm.title === null || String(fm.title).trim() === '') {
+		throw new ContentError(`${path}: missing required frontmatter field \`title\`.`);
+	}
+	if (fm.date === undefined || fm.date === null || String(fm.date).trim() === '') {
+		throw new ContentError(`${path}: missing required frontmatter field \`date\`.`);
+	}
+
+	const title = String(fm.title).trim();
+	const date = assertValidDate(normalizeDateInput(fm.date), 'date', path);
+
+	let updated: string | null = null;
+	if (fm.updated !== undefined && fm.updated !== null && String(fm.updated).trim() !== '') {
+		updated = assertValidDate(normalizeDateInput(fm.updated), 'updated', path);
+	}
+
+	const explicitSlug = fm.slug !== undefined && fm.slug !== null && String(fm.slug).trim() !== '';
+	const slug = slugify(explicitSlug ? String(fm.slug) : filenameOf(path));
+	if (slug === '') {
+		throw new ContentError(
+			`${path}: could not derive a non-empty slug from ${explicitSlug ? 'the `slug` field' : 'the filename'}.`
+		);
+	}
+
+	const descriptionRaw = fm.description ?? fm.excerpt;
+	const description =
+		descriptionRaw !== undefined && descriptionRaw !== null && String(descriptionRaw).trim() !== ''
+			? String(descriptionRaw).trim()
+			: null;
+
+	let tags: string[] = [];
+	if (fm.tags !== undefined && fm.tags !== null) {
+		if (!Array.isArray(fm.tags)) {
+			throw new ContentError(
+				`${path}: \`tags\` must be a YAML list (e.g. tags: [notes, sveltekit]), got ${typeof fm.tags}.`
+			);
+		}
+		tags = [...new Set(fm.tags.map(normalizeTag).filter((t) => t !== ''))];
+	}
+
+	const author =
+		fm.author !== undefined && fm.author !== null && String(fm.author).trim() !== ''
+			? String(fm.author).trim()
+			: null;
+
+	const draft = fm.draft === true;
+
+	return {
+		slug,
+		title,
+		date,
+		updated,
+		description,
+		tags,
+		author,
+		draft,
+		sourcePath: path,
+		body: parsed.content
+	};
+}
+
+/** Throw if any two sources resolve to the same slug, naming both files (edge case 3). */
+export function assertUniqueSlugs(sources: { slug: string; sourcePath: string }[]): void {
+	const bySlug = new Map<string, string>();
+	for (const item of sources) {
+		const existing = bySlug.get(item.slug);
+		if (existing) {
+			throw new ContentError(
+				`Duplicate slug "${item.slug}" produced by two files: ${existing} and ${item.sourcePath}. ` +
+					`Set a distinct \`slug\` in one file's frontmatter or rename it.`
+			);
+		}
+		bySlug.set(item.slug, item.sourcePath);
+	}
+}
+
+const RESERVED = new Set<string>(RESERVED_PAGE_SLUGS);
+
+/** Parse and validate one static page Markdown file. Throws ContentError. */
+export function parsePage(path: string, raw: string): PageSource {
+	let parsed: matter.GrayMatterFile<string>;
+	try {
+		parsed = matter(raw);
+	} catch (e: unknown) {
+		const detail = e instanceof Error ? e.message : String(e);
+		throw new ContentError(`${path}: could not parse YAML frontmatter — ${detail}`);
+	}
+
+	const fm = parsed.data as RawPageFrontmatter;
+
+	if (fm.title === undefined || fm.title === null || String(fm.title).trim() === '') {
+		throw new ContentError(`${path}: missing required frontmatter field \`title\`.`);
+	}
+
+	const title = String(fm.title).trim();
+	const explicitSlug = fm.slug !== undefined && fm.slug !== null && String(fm.slug).trim() !== '';
+	const slug = slugify(explicitSlug ? String(fm.slug) : filenameOf(path));
+	if (slug === '') {
+		throw new ContentError(
+			`${path}: could not derive a non-empty slug from ${explicitSlug ? 'the `slug` field' : 'the filename'}.`
+		);
+	}
+	if (RESERVED.has(slug)) {
+		throw new ContentError(
+			`${path}: slug "${slug}" is reserved by the engine (${RESERVED_PAGE_SLUGS.join(', ')}). ` +
+				`Rename the file or set a different \`slug\` in frontmatter.`
+		);
+	}
+
+	const descriptionRaw = fm.description ?? fm.excerpt;
+	const description =
+		descriptionRaw !== undefined && descriptionRaw !== null && String(descriptionRaw).trim() !== ''
+			? String(descriptionRaw).trim()
+			: null;
+
+	let order = 0;
+	if (fm.order !== undefined && fm.order !== null && String(fm.order).trim() !== '') {
+		const n = Number(fm.order);
+		if (!Number.isFinite(n)) {
+			throw new ContentError(`${path}: \`order\` must be a number (got ${JSON.stringify(fm.order)}).`);
+		}
+		order = n;
+	}
+
+	return {
+		slug,
+		title,
+		description,
+		draft: fm.draft === true,
+		order,
+		sourcePath: path,
+		body: parsed.content
+	};
+}