cosmolo 0.3.0

package/src/loaders.ts

@@ -0,0 +1,135 @@
+import { getArticle, getArticles, getArticlesByCategory, getArticlesBySeries, getArticlesByTag, getSlugs, getTags } from './articles.js';
+import { getCategorySlugs, getCategoryLabel, getCategoryDescription } from './categories.js';
+import { getPage, getPageSlugs } from './pages.js';
+import type { Article, ResolvedCosmoloConfig } from './types.js';
+
+/**
+ * Factory for the article listing page load function.
+ *
+ * @example
+ * // src/routes/+page.server.ts
+ * import { createArticlesLoader } from 'cosmolo';
+ * import config from '../../cosmolo.config';
+ * export const load = createArticlesLoader(config);
+ */
+export function createArticlesLoader(config: ResolvedCosmoloConfig) {
+	return () => ({ articles: getArticles(config) });
+}
+
+/**
+ * Factory for a single article page load function.
+ * Resolves manual related articles, series prev/next, and git updated date.
+ *
+ * @example
+ * // src/routes/articles/[slug]/+page.server.ts
+ * import { createArticleLoader } from 'cosmolo';
+ * import config from '../../../../cosmolo.config';
+ * export const entries = () => getSlugs(config).map(slug => ({ slug }));
+ * export const load = createArticleLoader(config);
+ */
+export function createArticleLoader(
+	config: ResolvedCosmoloConfig,
+	options: { getUpdatedAt?: (slug: string) => string } = {}
+) {
+	return async ({ params }: { params: { slug: string } }) => {
+		const article = await getArticle(config, params.slug);
+		const updatedAt = options.getUpdatedAt?.(params.slug) ?? '';
+
+		let related: Article[];
+		if (article.related.length > 0) {
+			const all = getArticles(config);
+			related = article.related
+				.map((s) => all.find((a) => a.slug === s))
+				.filter((a): a is Article => a !== undefined)
+				.slice(0, 4);
+		} else {
+			related = getArticlesByCategory(config, article.category, params.slug).slice(0, 4);
+		}
+
+		let seriesPrev: Article | null = null;
+		let seriesNext: Article | null = null;
+		let seriesTotal = 0;
+		if (article.series) {
+			const seriesArticles = getArticlesBySeries(config, article.series);
+			seriesTotal = seriesArticles.length;
+			const idx = seriesArticles.findIndex((a) => a.slug === params.slug);
+			seriesPrev = idx > 0 ? seriesArticles[idx - 1] : null;
+			seriesNext = idx < seriesArticles.length - 1 ? seriesArticles[idx + 1] : null;
+		}
+
+		return { article, related, updatedAt, seriesPrev, seriesNext, seriesTotal };
+	};
+}
+
+/**
+ * Factory for the category listing page load function.
+ *
+ * @example
+ * // src/routes/categories/[slug]/+page.server.ts
+ * import { createCategoryLoader } from 'cosmolo';
+ * import config from '../../../../cosmolo.config';
+ * export const entries = () => getCategorySlugs(config).map(slug => ({ slug }));
+ * export const load = createCategoryLoader(config);
+ */
+export function createCategoryLoader(config: ResolvedCosmoloConfig) {
+	return ({ params }: { params: { slug: string } }) => {
+		const { slug } = params;
+		return {
+			slug,
+			label: getCategoryLabel(config, slug),
+			description: getCategoryDescription(config, slug),
+			articles: getArticlesByCategory(config, slug),
+		};
+	};
+}
+
+/**
+ * Factory for the tag listing page load function.
+ *
+ * @example
+ * // src/routes/tags/[tag]/+page.server.ts
+ * import { createTagLoader } from 'cosmolo';
+ * import config from '../../../../cosmolo.config';
+ * export const entries = () => getTags(config).map(tag => ({ tag }));
+ * export const load = createTagLoader(config);
+ */
+export function createTagLoader(config: ResolvedCosmoloConfig) {
+	return ({ params }: { params: { tag: string } }) => ({
+		tag: params.tag,
+		articles: getArticlesByTag(config, params.tag),
+	});
+}
+
+/**
+ * Factory for the static page load function.
+ *
+ * @example
+ * // src/routes/(pages)/[slug]/+page.server.ts
+ * import { createPageLoader } from 'cosmolo';
+ * import config from '../../../../cosmolo.config';
+ * export const entries = () => getPageSlugs(config).map(slug => ({ slug }));
+ * export const load = createPageLoader(config);
+ */
+export function createPageLoader(config: ResolvedCosmoloConfig) {
+	return async ({ params }: { params: { slug: string } }) => ({
+		page: await getPage(config, params.slug),
+	});
+}
+
+// ─── entries generators ───────────────────────────────────────────────────────
+
+export function createArticleEntries(config: ResolvedCosmoloConfig) {
+	return () => getSlugs(config).map((slug) => ({ slug }));
+}
+
+export function createCategoryEntries(config: ResolvedCosmoloConfig) {
+	return () => getCategorySlugs(config).map((slug) => ({ slug }));
+}
+
+export function createTagEntries(config: ResolvedCosmoloConfig) {
+	return () => getTags(config).map((tag) => ({ tag }));
+}
+
+export function createPageEntries(config: ResolvedCosmoloConfig) {
+	return () => getPageSlugs(config).map((slug) => ({ slug }));
+}

package/src/markdown.ts

@@ -0,0 +1,74 @@
+import { marked } from 'marked';
+import type { TocEntry } from './types.js';
+
+function slugifyHeading(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/<[^>]+>/g, '')
+		.replace(/[^\w\s-]/g, '')
+		.trim()
+		.replace(/\s+/g, '-');
+}
+
+marked.use({
+	extensions: [
+		{
+			name: 'youtube',
+			level: 'block',
+			start(src: string) {
+				return src.indexOf('::youtube[');
+			},
+			tokenizer(src: string) {
+				const match = /^::youtube\[([^\]]+)\]/.exec(src);
+				if (match) return { type: 'youtube', raw: match[0], videoId: match[1].trim() };
+			},
+			renderer(token) {
+				const { videoId } = token as unknown as { videoId: string };
+				return `<div class="youtube-embed"><iframe src="https://www.youtube.com/embed/${videoId}" title="YouTube video" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe></div>\n`;
+			},
+		},
+	],
+});
+
+marked.use({
+	renderer: {
+		link({ href, title, text }: { href: string; title?: string | null; text: string }) {
+			const isExternal = /^https?:\/\//.test(href ?? '');
+			const rel = isExternal ? ' target="_blank" rel="noopener noreferrer"' : '';
+			const titleAttr = title ? ` title="${title}"` : '';
+			return `<a href="${href}"${titleAttr}${rel}>${text}</a>`;
+		},
+		heading({ text, depth }: { text: string; depth: number }) {
+			const id = slugifyHeading(text);
+			return `<h${depth} id="${id}">${text}</h${depth}>\n`;
+		},
+	},
+});
+
+export async function renderMarkdown(content: string): Promise<string> {
+	return marked.parse(content);
+}
+
+export function generateToc(content: string): TocEntry[] {
+	const entries: TocEntry[] = [];
+	const seenIds = new Map<string, number>();
+	const headingRegex = /^(#{2,6})\s+(.+?)$/gm;
+	let match;
+	while ((match = headingRegex.exec(content)) !== null) {
+		const level = match[1].length;
+		const rawText = match[2].trim();
+		const plainText = rawText
+			.replace(/\*\*([^*]+)\*\*/g, '$1')
+			.replace(/\*([^*]+)\*/g, '$1')
+			.replace(/__([^_]+)__/g, '$1')
+			.replace(/_([^_]+)_/g, '$1')
+			.replace(/`([^`]+)`/g, '$1')
+			.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+		const baseId = slugifyHeading(plainText);
+		const count = seenIds.get(baseId) ?? 0;
+		const id = count === 0 ? baseId : `${baseId}-${count}`;
+		seenIds.set(baseId, count + 1);
+		entries.push({ level, id, text: plainText });
+	}
+	return entries;
+}

package/src/pages.ts

@@ -0,0 +1,23 @@
+import matter from 'gray-matter';
+import { renderMarkdown } from './markdown.js';
+import type { Page, ResolvedCosmoloConfig } from './types.js';
+import { rawPageFiles } from 'cosmolo:content';
+
+function slugFromPath(filePath: string, dir: string): string {
+	const prefix = dir.replace(/^\//, '');
+	return filePath.replace(new RegExp(`^/?${prefix}/`), '').replace(/\.md$/, '');
+}
+
+export function getPageSlugs(config: ResolvedCosmoloConfig): string[] {
+	return Object.keys(rawPageFiles).map((p) => slugFromPath(p, config.pagesDir));
+}
+
+export async function getPage(config: ResolvedCosmoloConfig, slug: string): Promise<Page> {
+	const dir = config.pagesDir.replace(/^\//, '');
+	const filePath = `/${dir}/${slug}.md`;
+	const raw = rawPageFiles[filePath];
+	if (raw === undefined) throw new Error(`Page not found: ${slug}`);
+	const { data, content } = matter(raw);
+	const html = await renderMarkdown(content);
+	return { slug, title: String(data.title ?? slug), html };
+}

package/src/plugin.ts

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import type { Plugin } from 'vite';
+import type { CosmoloConfig } from './types.js';
+import { resolveConfig } from './config.js';
+
+const VIRTUAL_ID = 'cosmolo:content';
+const RESOLVED_ID = '\0cosmolo:content';
+
+/**
+ * Vite plugin that generates the `cosmolo:content` virtual module.
+ *
+ * Content files are bundled via `import.meta.glob` (evaluated at build time).
+ * JSON config files (categories, site config) are inlined as object literals so
+ * the runtime code has no `fs` dependency — required for Cloudflare Workers and
+ * other serverless runtimes.
+ *
+ * Usage in vite.config.ts:
+ *   import { cosmoloPlugin } from 'cosmolo/plugin';
+ *   plugins: [sveltekit(), cosmoloPlugin({ articlesDir: 'content/articles' })]
+ */
+export function cosmoloPlugin(userConfig: CosmoloConfig = {}): Plugin {
+	const config = resolveConfig(userConfig);
+
+	const articlesDir = '/' + config.articlesDir.replace(/^\/|\/$/g, '');
+	const pagesDir = '/' + config.pagesDir.replace(/^\/|\/$/g, '');
+
+	const categoriesAbsPath = path.resolve(process.cwd(), config.categoriesConfigPath);
+	const siteConfigAbsPath = path.resolve(process.cwd(), config.siteConfigPath);
+
+	return {
+		name: 'cosmolo',
+		resolveId(id) {
+			if (id === VIRTUAL_ID) return RESOLVED_ID;
+		},
+		load(id) {
+			if (id !== RESOLVED_ID) return;
+
+			this.addWatchFile(categoriesAbsPath);
+			this.addWatchFile(siteConfigAbsPath);
+
+			const categoriesData = JSON.parse(fs.readFileSync(categoriesAbsPath, 'utf-8'));
+			const siteConfigData = JSON.parse(fs.readFileSync(siteConfigAbsPath, 'utf-8'));
+
+			return `
+export const rawMdFiles = import.meta.glob(
+  '${articlesDir}/*.md',
+  { query: '?raw', import: 'default', eager: true }
+);
+
+export const svxModules = import.meta.glob(
+  '${articlesDir}/*.svx',
+  { eager: true }
+);
+
+export const rawPageFiles = import.meta.glob(
+  '${pagesDir}/*.md',
+  { query: '?raw', import: 'default', eager: true }
+);
+
+export const categoriesData = ${JSON.stringify(categoriesData)};
+
+export const siteConfigData = ${JSON.stringify(siteConfigData)};
+`.trim();
+		},
+	};
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+// ─── Package configuration ────────────────────────────────────────────────────
+
+export interface CosmoloConfig {
+	/** Directory containing article files (.md, .svx). @default 'src/content/articles' */
+	articlesDir?: string;
+	/** Directory containing static page files (.md). @default 'src/content/pages' */
+	pagesDir?: string;
+	/** Path to site configuration JSON. @default 'config/site.json' */
+	siteConfigPath?: string;
+	/** Path to categories configuration JSON. @default 'config/categories.json' */
+	categoriesConfigPath?: string;
+}
+
+export type ResolvedCosmoloConfig = Required<CosmoloConfig>;
+
+// ─── Content types ────────────────────────────────────────────────────────────
+
+export interface TocEntry {
+	level: number;
+	id: string;
+	text: string;
+}
+
+export interface ArticleFrontmatter {
+	title: string;
+	category: string;
+	excerpt: string;
+	sort: number;
+	date: string;
+	tags: string[];
+	series?: string;
+	seriesOrder?: number;
+	draft: boolean;
+	related: string[];
+}
+
+export interface Article extends ArticleFrontmatter {
+	slug: string;
+	html: string;
+	markdown: string;
+	toc: TocEntry[];
+}
+
+export interface Page {
+	slug: string;
+	title: string;
+	html: string;
+}
+
+export interface CategoryEntry {
+	slug: string;
+	label: string;
+	description: string;
+}
+
+export interface SiteConfig {
+	url: string;
+	name: string;
+	description: string;
+	twitterHandle: string;
+	fallbackCategoryLabel: string;
+	articlesPerPage: number;
+	ogImage: { mode: 'static' | 'generated' };
+	api: { articleBody: 'html' | 'markdown' | 'plaintext' };
+}

package/src/virtual.d.ts

@@ -0,0 +1,8 @@
+declare module 'cosmolo:content' {
+	const rawMdFiles: Record<string, string>;
+	const svxModules: Record<string, { metadata: Record<string, unknown>; default: unknown }>;
+	const rawPageFiles: Record<string, string>;
+	const categoriesData: Record<string, { label: string; description: string }>;
+	const siteConfigData: import('./types.js').SiteConfig;
+	export { rawMdFiles, svxModules, rawPageFiles, categoriesData, siteConfigData };
+}

package/templates/full/lib/components/Pagination.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+	interface Props {
+		total: number;
+		perPage: number;
+		currentPage: number;
+		onPageChange: (page: number) => void;
+	}
+
+	const { total, perPage, currentPage, onPageChange }: Props = $props();
+
+	const totalPages = $derived(Math.ceil(total / perPage));
+
+	const pageItems = $derived.by(() => {
+		if (totalPages <= 7) {
+			return Array.from({ length: totalPages }, (_, i) => i + 1);
+		}
+		const items: number[] = [];
+		const delta = 2;
+		const left = currentPage - delta;
+		const right = currentPage + delta;
+
+		items.push(1);
+		if (left > 2) items.push(0);
+
+		for (let p = Math.max(2, left); p <= Math.min(totalPages - 1, right); p++) {
+			items.push(p);
+		}
+
+		if (right < totalPages - 1) items.push(0);
+		items.push(totalPages);
+
+		return items;
+	});
+</script>
+
+{#if totalPages > 1}
+	<nav aria-label="Pagination">
+		<button
+			disabled={currentPage === 1}
+			onclick={() => onPageChange(currentPage - 1)}
+			aria-label="Previous page"
+		>
+			&larr;
+		</button>
+
+		{#each pageItems as item}
+			{#if item === 0}
+				<span aria-hidden="true">&hellip;</span>
+			{:else}
+				<button
+					onclick={() => onPageChange(item)}
+					aria-label="Page {item}"
+					aria-current={item === currentPage ? 'page' : undefined}
+				>
+					{item}
+				</button>
+			{/if}
+		{/each}
+
+		<button
+			disabled={currentPage === totalPages}
+			onclick={() => onPageChange(currentPage + 1)}
+			aria-label="Next page"
+		>
+			&rarr;
+		</button>
+	</nav>
+{/if}

package/templates/full/routes/(pages)/[slug]/+page.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import type { PageData } from './$types';
+
+	const { data }: { data: PageData } = $props();
+</script>
+
+<article>
+	<div class="container">
+		<h1>{data.page.title}</h1>
+		<div class="prose">
+			{@html data.page.html}
+		</div>
+	</div>
+</article>

package/templates/full/routes/+page.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+	import { getCategoryLabel } from 'cosmolo';
+	import Pagination from '$lib/components/Pagination.svelte';
+	import config from '../../cosmolo.config';
+	import type { PageData } from './$types';
+
+	const { data }: { data: PageData } = $props();
+
+	const perPage = 10;
+
+	let query = $state('');
+	let currentPage = $state(1);
+
+	const filtered = $derived(
+		query.trim() === ''
+			? data.articles
+			: (() => {
+					const q = query.toLowerCase();
+					return data.articles.filter(
+						(a) =>
+							a.title.toLowerCase().includes(q) ||
+							a.excerpt.toLowerCase().includes(q) ||
+							getCategoryLabel(config, a.category).toLowerCase().includes(q)
+					);
+				})()
+	);
+
+	$effect(() => {
+		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+		query;
+		currentPage = 1;
+	});
+
+	const paginated = $derived(filtered.slice((currentPage - 1) * perPage, currentPage * perPage));
+</script>
+
+<section>
+	<div class="container">
+		<h1>Articles</h1>
+
+		<div>
+			<input
+				type="search"
+				placeholder="Search articles…"
+				bind:value={query}
+				autocomplete="off"
+			/>
+			{#if query.trim() !== ''}
+				<p>{filtered.length} result{filtered.length !== 1 ? 's' : ''} for &ldquo;{query}&rdquo;</p>
+			{/if}
+		</div>
+
+		{#if data.articles.length === 0}
+			<p>No articles yet.</p>
+		{:else if filtered.length === 0}
+			<p>No articles matched your search.</p>
+		{:else}
+			<ul>
+				{#each paginated as article}
+					<li>
+						<a href="/articles/{article.slug}">
+							<span>{getCategoryLabel(config, article.category)}</span>
+							{#if article.date}
+								<time datetime={article.date}>{article.date}</time>
+							{/if}
+							<h2>{article.title}</h2>
+							<p>{article.excerpt}</p>
+						</a>
+					</li>
+				{/each}
+			</ul>
+
+			<Pagination
+				total={filtered.length}
+				{perPage}
+				{currentPage}
+				onPageChange={(p) => {
+					currentPage = p;
+					window.scrollTo({ top: 0, behavior: 'smooth' });
+				}}
+			/>
+		{/if}
+	</div>
+</section>

package/templates/full/routes/articles/[slug]/+page.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+	import { getCategoryLabel, getSvxComponent } from 'cosmolo';
+	import config from '../../../../cosmolo.config';
+	import type { PageData } from './$types';
+	import type { Component } from 'svelte';
+
+	const { data }: { data: PageData } = $props();
+
+	const SvxComponent = $derived(getSvxComponent(config, data.article.slug) as Component | undefined);
+
+	const hasToc = $derived(data.article.toc.length >= 2);
+</script>
+
+<article>
+	<header>
+		<div>
+			<a href="/categories/{data.article.category}">
+				{getCategoryLabel(config, data.article.category)}
+			</a>
+			{#if data.article.date}
+				<time datetime={data.article.date}>{data.article.date}</time>
+			{/if}
+			{#if data.updatedAt && data.updatedAt !== data.article.date}
+				<span>Updated: <time datetime={data.updatedAt}>{data.updatedAt}</time></span>
+			{/if}
+		</div>
+		<h1>{data.article.title}</h1>
+		<p>{data.article.excerpt}</p>
+		{#if data.article.tags.length > 0}
+			<div>
+				{#each data.article.tags as tag}
+					<a href="/tags/{tag}">#{tag}</a>
+				{/each}
+			</div>
+		{/if}
+	</header>
+
+	{#if data.article.series}
+		<nav>
+			<p>Series: {data.article.series} (Part {data.article.seriesOrder ?? '?'} of {data.seriesTotal})</p>
+			<div>
+				{#if data.seriesPrev}
+					<a href="/articles/{data.seriesPrev.slug}">&larr; {data.seriesPrev.title}</a>
+				{/if}
+				{#if data.seriesNext}
+					<a href="/articles/{data.seriesNext.slug}">{data.seriesNext.title} &rarr;</a>
+				{/if}
+			</div>
+		</nav>
+	{/if}
+
+	{#if hasToc}
+		<nav aria-label="Table of contents">
+			<p>Contents</p>
+			<ol>
+				{#each data.article.toc as entry}
+					<li style="padding-left: {(entry.level - 2) * 1}rem">
+						<a href="#{entry.id}">{entry.text}</a>
+					</li>
+				{/each}
+			</ol>
+		</nav>
+	{/if}
+
+	<div class="prose">
+		{#if SvxComponent}
+			<SvxComponent />
+		{:else}
+			{@html data.article.html}
+		{/if}
+	</div>
+
+	<footer>
+		<a href="/">&larr; Back to articles</a>
+
+		{#if data.related.length > 0}
+			<section>
+				<h2>Related articles</h2>
+				<ul>
+					{#each data.related as rel}
+						<li>
+							<a href="/articles/{rel.slug}">
+								<span>{rel.title}</span>
+								<span>{rel.excerpt}</span>
+							</a>
+						</li>
+					{/each}
+				</ul>
+			</section>
+		{/if}
+	</footer>
+</article>

package/templates/full/routes/categories/[slug]/+page.svelte

@@ -0,0 +1,58 @@
+<script lang="ts">
+	import Pagination from '$lib/components/Pagination.svelte';
+	import type { PageData } from './$types';
+
+	const { data }: { data: PageData } = $props();
+
+	const perPage = 10;
+	let currentPage = $state(1);
+
+	$effect(() => {
+		// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+		data.slug;
+		currentPage = 1;
+	});
+
+	const paginated = $derived(
+		data.articles.slice((currentPage - 1) * perPage, currentPage * perPage)
+	);
+</script>
+
+<section>
+	<div class="container">
+		<header>
+			<h1>{data.label}</h1>
+			{#if data.description}
+				<p>{data.description}</p>
+			{/if}
+		</header>
+
+		{#if data.articles.length === 0}
+			<p>No articles in this category yet.</p>
+		{:else}
+			<ul>
+				{#each paginated as article}
+					<li>
+						<a href="/articles/{article.slug}">
+							{#if article.date}
+								<time datetime={article.date}>{article.date}</time>
+							{/if}
+							<h2>{article.title}</h2>
+							<p>{article.excerpt}</p>
+						</a>
+					</li>
+				{/each}
+			</ul>
+
+			<Pagination
+				total={data.articles.length}
+				{perPage}
+				{currentPage}
+				onPageChange={(p) => {
+					currentPage = p;
+					window.scrollTo({ top: 0, behavior: 'smooth' });
+				}}
+			/>
+		{/if}
+	</div>
+</section>