@wrikka/create-docs 0.1.0

package/src/runtime/pages/PluginsPage.tsx

@@ -0,0 +1,249 @@
+import { createSignal, For, Show } from "solid-js";
+import type { PluginInfo } from "../config";
+import { useDocs } from "../context";
+
+const builtIn: PluginInfo[] = [
+	{
+		name: "MCP server",
+		description:
+			"Expose docs search and content as Model Context Protocol tools at /mcp.",
+		icon: "i-mdi:robot-outline",
+		version: "built-in",
+	},
+	{
+		name: "LLM documentation",
+		description:
+			"Auto-generated /llms.txt and /llms-plugins.txt so AI agents can consume the docs.",
+		icon: "i-mdi:text-box-outline",
+		version: "built-in",
+	},
+	{
+		name: "GitHub OAuth",
+		description:
+			"Sign in with GitHub and save docs directly back to a repository.",
+		icon: "i-mdi:github",
+		version: "built-in",
+	},
+	{
+		name: "@wrikka/create-docs",
+		description: "The core docs runtime with SolidJS and TanStack Router.",
+		icon: "i-mdi:book-open-page-variant",
+		version: "built-in",
+	},
+	{
+		name: "OpenAPI adapter",
+		description: "Render OpenAPI specs as interactive API references.",
+		icon: "i-mdi:api",
+		version: "built-in",
+	},
+	{
+		name: "oRPC adapter",
+		description: "Generate docs from oRPC router definitions.",
+		icon: "i-mdi:lan-connect",
+		version: "built-in",
+	},
+	{
+		name: "Elysia adapter",
+		description: "Auto-generate docs from Elysia Eden treaties.",
+		icon: "i-mdi:server",
+		version: "built-in",
+	},
+	{
+		name: "Nitro adapter",
+		description: "Reference Nitro server handlers and API routes.",
+		icon: "i-mdi:fire",
+		version: "built-in",
+	},
+	{
+		name: "Search & command palette",
+		description:
+			"MiniSearch-backed full-text search with a two-column command palette.",
+		icon: "i-mdi:magnify",
+		version: "built-in",
+	},
+	{
+		name: "PWA",
+		description:
+			"Service worker, web manifest, and offline support out of the box.",
+		icon: "i-mdi:cellphone-arrow-down",
+		version: "built-in",
+	},
+	{
+		name: "SEO feeds",
+		description: "Sitemap, RSS/Atom, robots.txt, and Open Graph generation.",
+		icon: "i-mdi:rss",
+		version: "built-in",
+	},
+];
+
+export function PluginsPage() {
+	const config = useDocs();
+	const [copied, setCopied] = createSignal<string | null>(null);
+
+	const copyInstall = (name: string, cmd: string) => {
+		navigator.clipboard.writeText(cmd).catch(() => {});
+		setCopied(name);
+		setTimeout(() => setCopied(null), 1500);
+	};
+
+	const plugins = () =>
+		(config.plugins ?? []).length > 0 ? config.plugins : builtIn;
+
+	const categories = () => {
+		const list = plugins() ?? [];
+		const groups = new Map<string, typeof list>();
+		for (const p of list) {
+			const cat = p.name.startsWith("@")
+				? "Packages"
+				: p.name.includes("adapter")
+					? "Adapters"
+					: p.name.startsWith("MCP") ||
+							p.name.includes("LLM") ||
+							p.name.includes("OAuth") ||
+							p.name.includes("PWA") ||
+							p.name.includes("SEO") ||
+							p.name.includes("Search")
+						? "Integrations"
+						: "Core";
+			const g = groups.get(cat) ?? [];
+			g.push(p);
+			groups.set(cat, g);
+		}
+		const order = ["Core", "Integrations", "Adapters", "Packages"];
+		return [...groups.entries()].sort(([a], [b]) => {
+			const ia = order.indexOf(a);
+			const ib = order.indexOf(b);
+			if (ia !== -1 && ib !== -1) return ia - ib;
+			if (ia !== -1) return -1;
+			if (ib !== -1) return 1;
+			return a.localeCompare(b);
+		});
+	};
+
+	return (
+		<div class="max-w-5xl mx-auto px-6 py-10 pb-24">
+			<div class="flex items-start gap-3 mb-2">
+				<span class="i-mdi:puzzle text-3xl text-primary" aria-hidden="true" />
+				<div>
+					<h1 class="text-3xl font-bold m-0">Plugins</h1>
+					<p class="text-muted m-0">
+						Integrations, adapters, and extensions for this docs site.
+					</p>
+				</div>
+			</div>
+
+			<Show when={config.features?.mcp}>
+				<div class="mt-6 mb-8 border border-border rounded-lg p-4 bg-surface/30 flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3">
+					<div class="flex items-center gap-3">
+						<span
+							class="i-mdi:robot-outline text-2xl text-primary"
+							aria-hidden="true"
+						/>
+						<div>
+							<div class="font-medium text-foreground">MCP & LLM ready</div>
+							<div class="text-xs text-muted">
+								Point your MCP client at /mcp and grab /llms.txt
+							</div>
+						</div>
+					</div>
+					<div class="flex items-center gap-2">
+						<a
+							href="/llms.txt"
+							class="px-3 h-9 inline-flex items-center rounded-md border border-border bg-background text-xs text-muted hover:text-foreground hover:bg-surface transition-colors no-underline"
+						>
+							llms.txt
+						</a>
+						<a
+							href="/llms-plugins.txt"
+							class="px-3 h-9 inline-flex items-center rounded-md border border-border bg-background text-xs text-muted hover:text-foreground hover:bg-surface transition-colors no-underline"
+						>
+							llms-plugins.txt
+						</a>
+					</div>
+				</div>
+			</Show>
+
+			<Show when={(config.plugins ?? []).length === 0}>
+				<div class="border border-border rounded-lg p-4 bg-surface/30 mb-8">
+					<p class="text-sm text-muted m-0">
+						No custom plugins configured yet. These are built-in integrations
+						you can enable from your config.
+					</p>
+				</div>
+			</Show>
+
+			<For each={categories()}>
+				{([category, items]) => (
+					<section class="mb-10">
+						<h2 class="text-lg font-semibold mb-3 flex items-center gap-2">
+							<span class="i-mdi:folder-open-outline" aria-hidden="true" />
+							{category}
+							<span class="ml-auto text-xs font-normal text-muted">
+								{items.length}
+							</span>
+						</h2>
+						<div class="grid sm:grid-cols-2 lg:grid-cols-3 gap-4">
+							<For each={items}>
+								{(p) => (
+									<article class="border border-border rounded-xl p-5 flex flex-col gap-3 bg-surface/30 hover:border-focus transition-colors">
+										<div class="flex items-center gap-3">
+											<Show when={p.icon}>
+												<span
+													class={`${p.icon} text-2xl text-primary`}
+													aria-hidden="true"
+												/>
+											</Show>
+											<div class="min-w-0 flex-1">
+												<h3 class="font-semibold text-sm m-0 truncate">
+													{p.name}
+												</h3>
+												<Show when={p.version}>
+													<span class="text-[10px] text-muted">
+														{p.version}
+													</span>
+												</Show>
+											</div>
+											<Show when={p.url}>
+												<a
+													href={p.url}
+													target="_blank"
+													rel="noreferrer"
+													aria-label={`${p.name} docs`}
+													class="w-7 h-7 inline-flex items-center justify-center rounded-md border border-border text-muted hover:text-foreground hover:bg-surface transition-colors"
+												>
+													<span class="i-mdi:open-in-new" aria-hidden="true" />
+												</a>
+											</Show>
+										</div>
+										<p class="text-sm text-muted m-0 flex-1 leading-relaxed">
+											{p.description}
+										</p>
+										<div class="flex items-center gap-2 pt-2 border-t border-border">
+											<Show when={p.install}>
+												<code class="text-[11px] bg-background border border-border rounded px-2 py-1 flex-1 truncate font-mono">
+													{p.install}
+												</code>
+												<button
+													type="button"
+													onClick={() => copyInstall(p.name, p.install!)}
+													class="px-2.5 h-7 rounded-md border border-border text-xs text-muted hover:text-foreground hover:bg-surface transition-colors cursor-pointer shrink-0"
+												>
+													{copied() === p.name ? "Copied!" : "Copy"}
+												</button>
+											</Show>
+											<Show when={!p.install}>
+												<span class="text-xs text-muted">
+													No install needed
+												</span>
+											</Show>
+										</div>
+									</article>
+								)}
+							</For>
+						</div>
+					</section>
+				)}
+			</For>
+		</div>
+	);
+}

package/src/runtime/pages/ShowcasePage.tsx

@@ -0,0 +1,202 @@
+import type { JSX } from "solid-js";
+import { createMemo, createSignal, For, Show } from "solid-js";
+import type { ShowcaseInfo } from "../config";
+import { useDocs } from "../context";
+
+function Card(props: { link?: string; children: JSX.Element }) {
+	const classes =
+		"group border border-border rounded-xl overflow-hidden bg-surface/30 hover:border-focus transition-all hover:-translate-y-0.5 hover:shadow-lg flex flex-col";
+	return props.link ? (
+		<a
+			href={props.link}
+			target="_blank"
+			rel="noreferrer"
+			class={`${classes} no-underline`}
+		>
+			{props.children}
+		</a>
+	) : (
+		<div class={classes}>{props.children}</div>
+	);
+}
+
+function ShowcaseCard(props: { item: ShowcaseInfo }) {
+	const { item } = props;
+	const coverStyle = () => {
+		if (item.image) return {};
+		const color = item.coverColor ?? "hsl(var(--color-primary) / 0.35)";
+		return {
+			background: `linear-gradient(135deg, ${color}, transparent)`,
+		};
+	};
+
+	return (
+		<Card link={item.link}>
+			<div
+				class="relative h-44 w-full bg-background border-b border-border overflow-hidden"
+				style={coverStyle()}
+			>
+				<Show
+					when={item.image}
+					fallback={
+						<div class="w-full h-full flex items-center justify-center">
+							<span
+								class={`${item.icon ?? "i-mdi:view-dashboard"} text-6xl text-primary/60`}
+								aria-hidden="true"
+							/>
+						</div>
+					}
+				>
+					<img
+						src={item.image!}
+						alt={`${item.label} preview`}
+						class="w-full h-full object-cover transition-transform duration-300 group-hover:scale-105"
+						loading="lazy"
+					/>
+				</Show>
+				<Show when={item.badge}>
+					<span class="absolute top-3 right-3 text-[10px] px-2 py-0.5 rounded-full bg-primary/15 text-primary font-medium">
+						{item.badge}
+					</span>
+				</Show>
+			</div>
+			<div class="p-5 flex flex-col gap-2 flex-1">
+				<div class="flex items-center gap-2">
+					<Show when={item.icon && !item.image}>
+						<span
+							class={`${item.icon} text-xl text-primary`}
+							aria-hidden="true"
+						/>
+					</Show>
+					<h3 class="font-semibold text-base m-0">{item.label}</h3>
+				</div>
+				<p class="text-sm text-muted m-0 flex-1 leading-relaxed">
+					{item.description}
+				</p>
+				<Show when={item.tags?.length}>
+					<div class="flex flex-wrap gap-1.5 mt-1">
+						<For each={item.tags}>
+							{(tag) => (
+								<span class="text-[10px] px-2 py-0.5 rounded-full bg-surface border border-border text-muted">
+									{tag}
+								</span>
+							)}
+						</For>
+					</div>
+				</Show>
+			</div>
+		</Card>
+	);
+}
+
+export function ShowcasePage() {
+	const config = useDocs();
+	const allItems = () => config.showcase ?? [];
+	const [search, setSearch] = createSignal("");
+	const [tag, setTag] = createSignal<string | null>(null);
+
+	const allTags = createMemo(() => {
+		const set = new Set<string>();
+		for (const item of allItems()) {
+			for (const t of item.tags ?? []) set.add(t);
+		}
+		return [...set].sort();
+	});
+
+	const filtered = createMemo(() => {
+		const q = search().toLowerCase();
+		const t = tag();
+		return allItems().filter((item) => {
+			const matchesSearch =
+				!q ||
+				item.label.toLowerCase().includes(q) ||
+				item.description.toLowerCase().includes(q) ||
+				item.tags?.some((tg) => tg.toLowerCase().includes(q));
+			const matchesTag = !t || item.tags?.includes(t);
+			return matchesSearch && matchesTag;
+		});
+	});
+
+	const featured = () => allItems()[0];
+	const rest = () =>
+		filtered().filter((i) => (featured() ? i.id !== featured()!.id : true));
+
+	return (
+		<div class="max-w-5xl mx-auto px-6 py-10 pb-24">
+			<div class="flex items-start gap-3 mb-2">
+				<span
+					class="i-mdi:view-dashboard text-3xl text-primary"
+					aria-hidden="true"
+				/>
+				<div>
+					<h1 class="text-3xl font-bold m-0">Showcase</h1>
+					<p class="text-muted m-0">
+						Featured projects and examples built with this ecosystem.
+					</p>
+				</div>
+			</div>
+
+			<div class="flex flex-col sm:flex-row gap-3 my-8">
+				<label class="flex items-center gap-2 flex-1 px-3 h-10 rounded-lg border border-border bg-surface text-muted text-sm">
+					<span class="i-mdi:magnify" aria-hidden="true" />
+					<input
+						type="search"
+						value={search()}
+						onInput={(e) => setSearch(e.currentTarget.value)}
+						placeholder="Filter showcase…"
+						aria-label="Filter showcase"
+						class="bg-transparent outline-none border-none w-full text-foreground placeholder:text-muted"
+					/>
+				</label>
+				<div class="flex flex-wrap gap-2">
+					<button
+						type="button"
+						onClick={() => setTag(null)}
+						class={`px-3 h-9 rounded-full text-xs border transition-colors cursor-pointer ${
+							tag() == null
+								? "bg-primary text-primary-foreground border-primary"
+								: "bg-surface text-muted border-border hover:border-focus"
+						}`}
+					>
+						All
+					</button>
+					<For each={allTags()}>
+						{(t) => (
+							<button
+								type="button"
+								onClick={() => setTag(t)}
+								class={`px-3 h-9 rounded-full text-xs border transition-colors cursor-pointer ${
+									tag() === t
+										? "bg-primary text-primary-foreground border-primary"
+										: "bg-surface text-muted border-border hover:border-focus"
+								}`}
+							>
+								{t}
+							</button>
+						)}
+					</For>
+				</div>
+			</div>
+
+			<Show when={!search() && !tag() && featured()}>
+				<section class="mb-10">
+					<h2 class="text-lg font-semibold mb-3 text-muted">Featured</h2>
+					<div class="sm:max-w-2xl">
+						<ShowcaseCard item={featured()!} />
+					</div>
+				</section>
+			</Show>
+
+			<Show when={filtered().length === 0}>
+				<div class="flex flex-col items-center gap-3 py-16 rounded-lg border border-dashed border-border text-muted">
+					<span class="i-mdi:image-plus text-4xl" aria-hidden="true" />
+					<p class="m-0">No showcase items match your filters.</p>
+				</div>
+			</Show>
+
+			<div class="grid sm:grid-cols-2 lg:grid-cols-3 gap-5">
+				<For each={rest()}>{(item) => <ShowcaseCard item={item} />}</For>
+			</div>
+		</div>
+	);
+}

package/src/runtime/pwa.ts

@@ -0,0 +1,39 @@
+import type { DocsAppConfig } from "./config";
+
+/**
+ * Enables PWA support: injects the web-app manifest link and theme-color
+ * meta, then registers `/sw.js` when the browser supports service workers.
+ *
+ * The consumer is responsible for shipping `manifest.webmanifest` and
+ * `sw.js` as static assets (e.g. in `public/`).
+ */
+export function setupPwa(config: DocsAppConfig): void {
+	if (!config.features?.pwa) return;
+	if (typeof document === "undefined") return;
+
+	if (!document.querySelector('link[rel="manifest"]')) {
+		const link = document.createElement("link");
+		link.rel = "manifest";
+		link.href = "/manifest.webmanifest";
+		document.head.appendChild(link);
+	}
+
+	if (!document.querySelector('meta[name="theme-color"]')) {
+		const meta = document.createElement("meta");
+		meta.name = "theme-color";
+		meta.content =
+			config.theme?.defaultMode === "light" ? "#ffffff" : "#0b0d12";
+		document.head.appendChild(meta);
+	}
+
+	const canRegister =
+		"serviceWorker" in navigator &&
+		(location.protocol === "https:" ||
+			location.hostname === "localhost" ||
+			location.hostname === "127.0.0.1");
+	if (!canRegister) return;
+
+	navigator.serviceWorker.register("/sw.js").catch(() => {
+		// Service worker missing or registration blocked — offline mode off.
+	});
+}

package/src/runtime/router.tsx

@@ -0,0 +1,192 @@
+import {
+	createRootRoute,
+	createRoute,
+	createRouter,
+	redirect,
+} from "@tanstack/solid-router";
+import { trackPageView } from "./analytics";
+import { NotFound } from "./components/NotFound";
+import type { DocsAppConfig } from "./config";
+import { findApiCollection } from "./context";
+import { DocsLayout } from "./layouts/DocsLayout";
+import { AbTestPage } from "./pages/AbTestPage";
+import { AnalyticsPage } from "./pages/AnalyticsPage";
+import { ApiDiffPage } from "./pages/ApiDiffPage";
+import { ApiEndpointPage } from "./pages/ApiEndpointPage";
+import { BuilderPage } from "./pages/BuilderPage";
+import { ChangelogPage } from "./pages/ChangelogPage";
+import { CollectionPage } from "./pages/CollectionPage";
+import { CommunityPage } from "./pages/CommunityPage";
+import { CreatePage } from "./pages/CreatePage";
+import { DocPage } from "./pages/DocPage";
+import { EditPage } from "./pages/EditPage";
+import { HomePage } from "./pages/HomePage";
+import { IssuesPage } from "./pages/IssuesPage";
+import { OAuthCallbackPage } from "./pages/OAuthCallbackPage";
+import { PluginsPage } from "./pages/PluginsPage";
+import { ShowcasePage } from "./pages/ShowcasePage";
+
+export function createDocsRouter(config: DocsAppConfig) {
+	const rootRoute = createRootRoute({
+		component: () => <DocsLayout />,
+		errorComponent: () => <NotFound />,
+	});
+
+	const indexRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/",
+		...(config.home
+			? { component: HomePage }
+			: {
+					beforeLoad: () => {
+						const target =
+							config.defaultCollection ??
+							config.apiCollections?.[0]?.id ??
+							"docs";
+						throw redirect({
+							to: "/$collection",
+							params: { collection: target },
+						});
+					},
+				}),
+	});
+
+	const collectionRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "$collection",
+		component: CollectionPage,
+	});
+
+	// One detail route; the page component switches on collection type.
+	const editRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "edit/$collection/$docId",
+		component: EditPage,
+	});
+
+	const detailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "$collection/$docId",
+		component: () => {
+			const params = detailRoute.useParams();
+			return findApiCollection(config, params().collection) ? (
+				<ApiEndpointPage />
+			) : (
+				<DocPage />
+			);
+		},
+	});
+
+	const createPageRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "create",
+		component: CreatePage,
+	});
+
+	const builderRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "builder",
+		component: BuilderPage,
+	});
+
+	const abTestRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "ab/$collection/$docId",
+		component: AbTestPage,
+	});
+
+	const extraRoutes = [];
+	if (config.github?.releases) {
+		const changelogRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "changelog",
+			component: ChangelogPage,
+		});
+		extraRoutes.push(changelogRoute);
+	}
+
+	if (config.github?.contributors) {
+		const communityRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "community",
+			component: CommunityPage,
+		});
+		extraRoutes.push(communityRoute);
+	}
+
+	if (config.github?.issues) {
+		const issuesRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "issues",
+			component: IssuesPage,
+		});
+		extraRoutes.push(issuesRoute);
+	}
+
+	if (config.features?.analytics) {
+		const analyticsRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "analytics",
+			component: AnalyticsPage,
+		});
+		extraRoutes.push(analyticsRoute);
+	}
+
+	if (config.apiDiff) {
+		const apiDiffRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "api-diff",
+			component: ApiDiffPage,
+		});
+		extraRoutes.push(apiDiffRoute);
+	}
+
+	if (config.plugins?.length) {
+		const pluginsRoute = createRoute({
+			getParentRoute: () => rootRoute,
+			path: "plugins",
+			component: PluginsPage,
+		});
+		extraRoutes.push(pluginsRoute);
+	}
+
+	const showcaseRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "showcase",
+		component: ShowcasePage,
+	});
+	extraRoutes.push(showcaseRoute);
+
+	const oauthCallbackRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "auth/github/callback",
+		component: OAuthCallbackPage,
+	});
+	extraRoutes.push(oauthCallbackRoute);
+
+	const routeTree = rootRoute.addChildren([
+		indexRoute,
+		createPageRoute,
+		editRoute,
+		builderRoute,
+		abTestRoute,
+		...extraRoutes,
+		collectionRoute,
+		detailRoute,
+	]);
+
+	const router = createRouter({
+		routeTree,
+		defaultPreload: "intent",
+		scrollRestoration: true,
+		defaultNotFoundComponent: NotFound,
+	});
+
+	if (config.features?.analytics) {
+		router.subscribe("onResolved", ({ toLocation }) => {
+			trackPageView(toLocation.pathname, config.analytics?.endpoint);
+		});
+	}
+
+	return router;
+}