@axerity/cli 0.1.0

package/src/lib/server/og.ts

@@ -0,0 +1,140 @@
+import satori from 'satori';
+import { Resvg } from '@resvg/resvg-js';
+import type { OgConfig } from '$lib/types';
+
+const WIDTH = 1200;
+const HEIGHT = 630;
+
+interface OgFont {
+	data: ArrayBuffer;
+	weight: 400 | 600 | 700;
+}
+
+interface RenderInput {
+	title: string;
+	description?: string;
+	siteName: string;
+	og?: OgConfig;
+	fonts: OgFont[];
+	logo?: string;
+}
+
+function clamp(value: string, max: number): string {
+	const trimmed = value.trim();
+	return trimmed.length > max ? `${trimmed.slice(0, max - 1).trimEnd()}…` : trimmed;
+}
+
+export async function renderOgImage({
+	title,
+	description,
+	siteName,
+	og,
+	fonts,
+	logo
+}: RenderInput): Promise<Uint8Array> {
+	const background = og?.background ?? '#0a0a0a';
+	const foreground = og?.foreground ?? '#fafafa';
+	const muted = og?.muted ?? '#a1a1a1';
+	const accent = og?.accent ?? foreground;
+
+	const headline = clamp(title, 80);
+	const subtitle = description ? clamp(description, 140) : '';
+
+	const element = {
+		type: 'div',
+		props: {
+			style: {
+				width: '100%',
+				height: '100%',
+				display: 'flex',
+				flexDirection: 'column',
+				justifyContent: 'space-between',
+				padding: '80px',
+				backgroundColor: background,
+				color: foreground,
+				fontFamily: 'Geist'
+			},
+			children: [
+				{
+					type: 'div',
+					props: {
+						style: {
+							display: 'flex',
+							alignItems: 'center',
+							gap: '14px',
+							fontSize: '30px',
+							fontWeight: 600,
+							color: accent
+						},
+						children: [
+							logo
+								? {
+										type: 'img',
+										props: { src: logo, width: 30, height: 32 }
+									}
+								: {
+										type: 'div',
+										props: {
+											style: {
+												width: '20px',
+												height: '20px',
+												borderRadius: '6px',
+												backgroundColor: accent
+											},
+											children: ''
+										}
+									},
+							siteName
+						]
+					}
+				},
+				{
+					type: 'div',
+					props: {
+						style: { display: 'flex', flexDirection: 'column' },
+						children: [
+							{
+								type: 'div',
+								props: {
+									style: { display: 'flex', fontSize: '68px', fontWeight: 700, lineHeight: 1.1 },
+									children: headline
+								}
+							},
+							subtitle
+								? {
+										type: 'div',
+										props: {
+											style: {
+												display: 'flex',
+												marginTop: '24px',
+												fontSize: '32px',
+												lineHeight: 1.3,
+												color: muted
+											},
+											children: subtitle
+										}
+									}
+								: null
+						]
+					}
+				},
+				{
+					type: 'div',
+					props: {
+						style: { display: 'flex', fontSize: '26px', color: muted },
+						children: siteName.toLowerCase()
+					}
+				}
+			]
+		}
+	};
+
+	const svg = await satori(element, {
+		width: WIDTH,
+		height: HEIGHT,
+		fonts: fonts.map((f) => ({ name: 'Geist', data: f.data, weight: f.weight, style: 'normal' }))
+	});
+
+	const resvg = new Resvg(svg, { fitTo: { mode: 'width', value: WIDTH } });
+	return resvg.render().asPng();
+}

package/src/lib/state/search.svelte.ts

@@ -0,0 +1,9 @@
+class SearchState {
+	open = $state(false);
+
+	toggle() {
+		this.open = !this.open;
+	}
+}
+
+export const searchState = new SearchState();

package/src/lib/state/theme.svelte.ts

@@ -0,0 +1,58 @@
+/**
+ * Theme state
+ *
+ */
+import { browser } from '$app/environment';
+
+export type ThemePreference = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+
+const STORAGE_KEY = 'axerity-theme';
+
+function systemTheme(): ResolvedTheme {
+	if (!browser) return 'light';
+	return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+class ThemeState {
+	preference = $state<ThemePreference>('dark');
+	#system = $state<ResolvedTheme>('light');
+
+	resolved = $derived<ResolvedTheme>(this.preference === 'system' ? this.#system : this.preference);
+
+	constructor() {
+		if (!browser) return;
+
+		const stored = localStorage.getItem(STORAGE_KEY) as ThemePreference | null;
+		if (stored === 'light' || stored === 'dark' || stored === 'system') {
+			this.preference = stored;
+		}
+		this.#system = systemTheme();
+
+		const mq = window.matchMedia('(prefers-color-scheme: dark)');
+		mq.addEventListener('change', (e) => {
+			this.#system = e.matches ? 'dark' : 'light';
+			this.#apply();
+		});
+
+		this.#apply();
+	}
+
+	#apply() {
+		if (!browser) return;
+		const resolved = this.preference === 'system' ? this.#system : this.preference;
+		document.documentElement.classList.toggle('dark', resolved === 'dark');
+	}
+
+	set(preference: ThemePreference) {
+		this.preference = preference;
+		if (browser) localStorage.setItem(STORAGE_KEY, preference);
+		this.#apply();
+	}
+
+	toggle() {
+		this.set(this.resolved === 'dark' ? 'light' : 'dark');
+	}
+}
+
+export const theme = new ThemeState();

package/src/lib/types.ts

@@ -0,0 +1,216 @@
+/**
+ * Core data shapes for the docs engine.
+ *
+ */
+
+/** A single navigable page in the sidebar. */
+export interface NavLink {
+	title: string;
+	href: string;
+	/** Lucide icon name (see `$lib/icons`). */
+	icon?: string;
+	badge?: string;
+	/** Page description, used by prev/next navigation. */
+	description?: string;
+	/** HTTP method (API pages) — shown as a badge in the sidebar. */
+	method?: string;
+}
+
+/** A collapsible, nestable folder in the sidebar. */
+export interface NavGroup {
+	title: string;
+	icon?: string;
+	items: NavEntry[];
+	/** Expand by default (otherwise collapsed unless it holds the active page). */
+	defaultOpen?: boolean;
+}
+
+/** Either a page link or a nested group. */
+export type NavEntry = NavLink | NavGroup;
+
+/** A top-level titled section in the sidebar (a top-level content folder). */
+export interface NavSection {
+	title: string;
+	icon?: string;
+	items: NavEntry[];
+}
+
+/** A top-level entry in the global navbar. */
+export interface TopNavLink {
+	title: string;
+	href: string;
+	icon?: string;
+	match?: string;
+	external?: boolean;
+}
+
+/** One heading captured for the on-page table of contents. */
+export interface TocEntry {
+	id: string;
+	title: string;
+	/** Heading level, 2 = h2, 3 = h3 (h1 is the page title, excluded). */
+	depth: 2 | 3;
+}
+
+/**
+ * Page layout width.
+ * - `flat`  — full-bleed; the sidebar sits flush at the left edge (default).
+ * - `boxed` — centered within a max-width container on wide screens.
+ */
+export type LayoutVariant = 'flat' | 'boxed';
+
+/**
+ * A built-in theme preset. Each is a cohesive palette (and where it matters,
+ * font + corner radius) inspired by a well-known product's docs.
+ */
+export type ThemeName =
+	| 'neutral'
+	| 'stripe'
+	| 'vercel'
+	| 'linear'
+	| 'supabase'
+	| 'github'
+	| 'tailwind'
+	| 'mintlify'
+	| 'anthropic';
+
+export interface Version {
+	label: string;
+	href: string;
+}
+
+export interface Dropdown {
+	label: string;
+	icon?: string;
+	href: string;
+	match?: string;
+	tabs?: TopNavLink[];
+}
+
+export interface Logo {
+	light?: string;
+	dark?: string;
+	alt?: string;
+	href?: string;
+}
+
+export interface SocialLink {
+	icon: string;
+	href: string;
+	label?: string;
+}
+
+export interface FooterConfig {
+	note?: string;
+	links?: { title: string; href: string }[];
+}
+
+export interface Banner {
+	text: string;
+	href?: string;
+	id?: string;
+	dismissible?: boolean;
+}
+
+/**
+ * Sidebar appearance.
+ * - `flush`    — tinted panel flush to the edge with a divider (default).
+ * - `card`     — a bordered, rounded panel inset from the edges.
+ * - `floating` — a detached, rounded, shadowed card that floats in the margin.
+ */
+export interface SidebarConfig {
+	variant?: 'flush' | 'card' | 'floating';
+}
+
+export interface AnalyticsConfig {
+	plausible?: string;
+	googleAnalytics?: string;
+}
+
+/**
+ * Brand overrides. Set your own accent and corners on top of any `theme`
+ * preset. Colors take any CSS color value; `radius` takes a length like
+ * `0.5rem`. Applied with `!important` so they win over the preset.
+ */
+export interface BrandConfig {
+	accent?: string;
+	accentDark?: string;
+	accentContrast?: string;
+	radius?: string;
+}
+
+export interface OpenApiConfig {
+	/** Local path or http(s) URL to an OpenAPI 3 spec (JSON or YAML). */
+	spec: string;
+	/** Content folder for this reference (its own group). Default `api-reference`. */
+	output?: string;
+	/** Section title (defaults to the spec's `info.title`). */
+	title?: string;
+}
+
+export interface OgConfig {
+	/** Generate a per-page OpenGraph image. Off uses the static `ogImage`. */
+	enabled?: boolean;
+	background?: string;
+	foreground?: string;
+	muted?: string;
+	accent?: string;
+	/** Logo shown in the card. Defaults to the site logo (dark variant). */
+	logo?: string;
+}
+
+/** Site-wide configuration (the future `docs.json` equivalent). */
+export interface SiteConfig {
+	name: string;
+	tagline?: string;
+	description?: string;
+	url?: string;
+	ogImage?: string;
+	og?: OgConfig;
+	logo?: Logo;
+	topNav: TopNavLink[];
+	versions?: Version[];
+	dropdowns?: Dropdown[];
+	sidebarLinks?: { title: string; href: string }[];
+	social?: SocialLink[];
+	footer?: FooterConfig;
+	banner?: Banner;
+	analytics?: AnalyticsConfig;
+	brand?: BrandConfig;
+	openapi?: string | OpenApiConfig | OpenApiConfig[];
+	editLink?: string;
+	github?: string;
+	layout?: LayoutVariant;
+	theme?: ThemeName;
+	sidebar?: SidebarConfig;
+	/** Serve the whole site under a sub-path, e.g. "/docs". Empty = root. */
+	basePath?: string;
+}
+
+/**
+ * `meta.json`
+ *
+ */
+export interface FolderMeta {
+	title: string;
+	icon?: string;
+	pages?: string[];
+	/** When this folder is a nested group, expand it by default in the sidebar. */
+	defaultOpen?: boolean;
+}
+
+/** Frontmatter on a markdown page. */
+export interface PageFrontmatter {
+	title?: string;
+	description?: string;
+	icon?: string;
+	badge?: string;
+	/** `api` switches the page to the wide, TOC-less API reference layout. */
+	layout?: 'doc' | 'api';
+	/** HTTP method (API pages) — shown as a badge in the sidebar. */
+	method?: string;
+	/** Publish date (ISO); pages with a date appear in the RSS feed. */
+	date?: string;
+	/** Last-updated date (ISO), shown near the page footer. */
+	updated?: string;
+}

package/src/params/docpage.ts

@@ -0,0 +1,3 @@
+import type { ParamMatcher } from '@sveltejs/kit';
+
+export const match: ParamMatcher = (param) => !param.endsWith('.md');

package/src/params/mdfile.ts

@@ -0,0 +1,3 @@
+import type { ParamMatcher } from '@sveltejs/kit';
+
+export const match: ParamMatcher = (param) => param.endsWith('.md');

package/src/routes/+error.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { site } from '$lib/config/site';
+	import House from '@lucide/svelte/icons/house';
+	import BookOpen from '@lucide/svelte/icons/book-open';
+
+	const status = $derived(page.status);
+	const heading = $derived(status === 404 ? 'Page not found' : 'Something went wrong');
+	const message = $derived(
+		status === 404
+			? "Sorry, we couldn't find the page you're looking for. It may have been moved or removed."
+			: (page.error?.message ?? 'An unexpected error occurred.')
+	);
+</script>
+
+<svelte:head>
+	<title>{status} · {site.name}</title>
+</svelte:head>
+
+<div class="flex min-h-screen flex-col items-center justify-center gap-4 bg-bg px-6 text-center">
+	<p
+		class="font-mono text-[5rem] leading-none font-bold text-border-strong select-none sm:text-[7rem]"
+	>
+		{status}
+	</p>
+
+	<h1 class="text-2xl font-bold tracking-tight text-fg sm:text-3xl">{heading}</h1>
+	<p class="max-w-md text-fg-muted">{message}</p>
+
+	<div class="mt-3 flex flex-wrap items-center justify-center gap-3">
+		<a
+			href="/"
+			class="inline-flex items-center gap-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-contrast transition hover:opacity-90"
+		>
+			<BookOpen size={16} />
+			Back to docs
+		</a>
+		<a
+			href="/"
+			class="inline-flex items-center gap-2 rounded-md border border-border px-4 py-2 text-sm font-medium text-fg-muted transition hover:border-border-strong hover:text-fg"
+		>
+			<House size={16} />
+			Home
+		</a>
+	</div>
+</div>

package/src/routes/+layout.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import '@fontsource-variable/geist/index.css';
+	import '@fontsource-variable/geist-mono/index.css';
+	import '@shikijs/twoslash/style-rich.css';
+	import './layout.css';
+	import { base } from '$app/paths';
+	import Analytics from '$lib/components/docs/Analytics.svelte';
+	import { site } from '$lib/config/site';
+
+	let { children } = $props();
+</script>
+
+<svelte:head>
+	<link rel="icon" href="{base}/favicon.svg" type="image/svg+xml" />
+	{#if site.url}
+		<link
+			rel="alternate"
+			type="application/rss+xml"
+			title="{site.name} changelog"
+			href="{site.url}{base}/rss.xml"
+		/>
+	{/if}
+</svelte:head>
+<Analytics />
+{@render children()}

package/src/routes/[...path=mdfile]/+server.ts

@@ -0,0 +1,21 @@
+import { error } from '@sveltejs/kit';
+import { base } from '$app/paths';
+import { flatPages } from '$lib/content';
+import { getRawMarkdown } from '$lib/content/raw';
+import type { EntryGenerator, RequestHandler } from './$types';
+
+export const prerender = true;
+
+export const entries: EntryGenerator = () =>
+	flatPages.map((page) => ({ path: page.href.slice(base.length).replace(/^\//, '') + '.md' }));
+
+export const GET: RequestHandler = async ({ params }) => {
+	const slug = params.path.replace(/\.md$/, '');
+	const markdown = await getRawMarkdown(slug);
+
+	if (markdown == null) error(404, 'Not found');
+
+	return new Response(markdown, {
+		headers: { 'content-type': 'text/plain; charset=utf-8' }
+	});
+};

package/src/routes/[...slug=docpage]/+page.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { base } from '$app/paths';
+	import { DocsLayout } from '$lib';
+	import { site } from '$lib/config/site';
+	import { navFor, pathInVersion } from '$lib/content';
+	import type { PageProps } from './$types';
+
+	let { data }: PageProps = $props();
+
+	const nav = $derived(navFor(page.url.pathname));
+	const Content = $derived(data.component);
+	const fm = $derived(data.frontmatter);
+	const wide = $derived(fm.layout === 'api');
+
+	const editUrl = $derived(site.editLink ? `${site.editLink}/${data.sourcePath}` : undefined);
+
+	const pageTitle = $derived(fm.title ? `${fm.title} · ${site.name}` : site.name);
+	const pageDescription = $derived(fm.description ?? site.description ?? '');
+	const canonical = $derived(site.url ? site.url + page.url.pathname : undefined);
+	const ogImagePath = $derived(
+		site.og?.enabled
+			? `${base}/og/${data.sourcePath.replace(/\.md$/, '')}.png`
+			: `${base}${site.ogImage ?? '/og-image.png'}`
+	);
+	const ogImage = $derived(site.url ? site.url + ogImagePath : ogImagePath);
+</script>
+
+<svelte:head>
+	<title>{pageTitle}</title>
+	{#if pageDescription}
+		<meta name="description" content={pageDescription} />
+	{/if}
+	{#if canonical}
+		<link rel="canonical" href={canonical} />
+		<meta property="og:url" content={canonical} />
+	{/if}
+	<meta property="og:type" content="article" />
+	<meta property="og:site_name" content={site.name} />
+	<meta property="og:title" content={fm.title ?? site.name} />
+	{#if pageDescription}
+		<meta property="og:description" content={pageDescription} />
+	{/if}
+	<meta property="og:image" content={ogImage} />
+	<meta name="twitter:card" content="summary_large_image" />
+	<meta name="twitter:title" content={fm.title ?? site.name} />
+	{#if pageDescription}
+		<meta name="twitter:description" content={pageDescription} />
+	{/if}
+	<meta name="twitter:image" content={ogImage} />
+</svelte:head>
+
+<DocsLayout
+	{site}
+	sidebar={nav.sidebar}
+	flatPages={nav.flatPages}
+	{wide}
+	{editUrl}
+	updated={fm.updated}
+	resolveVersion={pathInVersion}
+>
+	<Content />
+</DocsLayout>

package/src/routes/[...slug=docpage]/+page.ts

@@ -0,0 +1,44 @@
+import { error, redirect } from '@sveltejs/kit';
+import { base } from '$app/paths';
+import type { Component } from 'svelte';
+import type { PageFrontmatter } from '$lib/types';
+import { defaultVersionPath, versioned } from '$lib/content';
+import type { EntryGenerator, PageLoad } from './$types';
+
+const pages = import.meta.glob<{ default: Component; metadata: PageFrontmatter }>(
+	'/src/content/docs/**/*.md',
+	{ eager: true }
+);
+
+const BASE = '/src/content/docs/';
+
+function pathToSlug(path: string): string {
+	const rel = path.slice(BASE.length).replace(/\.md$/, '');
+	return rel === 'index' ? '' : rel.replace(/\/index$/, '');
+}
+
+export const prerender = true;
+
+export const entries: EntryGenerator = () => {
+	const slugs = Object.keys(pages).map((path) => ({ slug: pathToSlug(path) }));
+	if (versioned) slugs.push({ slug: '' });
+	return slugs;
+};
+
+export const load: PageLoad = ({ params }) => {
+	const slug = params.slug;
+
+	if (!slug && versioned) redirect(307, `${base}${defaultVersionPath}`);
+
+	const candidates = slug ? [`${BASE}${slug}.md`, `${BASE}${slug}/index.md`] : [`${BASE}index.md`];
+	const path = candidates.find((p) => p in pages);
+
+	if (!path) error(404, 'Page not found');
+
+	const mod = pages[path];
+	return {
+		component: mod.default,
+		frontmatter: mod.metadata ?? {},
+		sourcePath: path.slice(BASE.length)
+	};
+};