@farming-labs/next 0.1.1-beta.4 → 0.1.2

package/dist/api-reference.d.mts

@@ -0,0 +1,9 @@
+import { resolveApiReferenceConfig } from "@farming-labs/docs/server";
+import { DocsConfig } from "@farming-labs/docs";
+
+//#region src/api-reference.d.ts
+declare function buildNextOpenApiDocument(config: DocsConfig): Record<string, unknown>;
+declare function withNextApiReferenceBanner(config: DocsConfig): DocsConfig;
+declare function createNextApiReference(config: DocsConfig): () => Promise<Response>;
+//#endregion
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner };

package/dist/api-reference.mjs

@@ -0,0 +1,488 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { ApiReference } from "@scalar/nextjs-api-reference";
+import { buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig } from "@farming-labs/docs/server";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/api-reference.tsx
+const ROUTE_FILE_RE = /^route\.(ts|tsx|js|jsx)$/;
+const METHOD_RE = /export\s+(?:async\s+function|function|const)\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/g;
+function getNextAppDir(root) {
+	if (existsSync(join(root, "src", "app"))) return "src/app";
+	return "app";
+}
+function normalizeRouteRoot(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "api";
+}
+function normalizeExcludeMatcher(value) {
+	return value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").replace(/\.(ts|tsx|js|jsx)$/i, "").replace(/\/route$/i, "");
+}
+function getRoutePathBase(config) {
+	const routeRoot = normalizeRouteRoot(config.routeRoot);
+	if (routeRoot === "app" || routeRoot === "src/app") return "";
+	if (routeRoot.startsWith("app/")) return `/${routeRoot.slice(4)}`;
+	if (routeRoot.startsWith("src/app/")) return `/${routeRoot.slice(8)}`;
+	return `/${routeRoot}`;
+}
+function resolveNextApiRouteRoot(root, config) {
+	const routeRoot = normalizeRouteRoot(config.routeRoot);
+	if (routeRoot === "app" || routeRoot.startsWith("app/") || routeRoot === "src/app" || routeRoot.startsWith("src/app/")) return join(root, ...routeRoot.split("/"));
+	return join(root, getNextAppDir(root), ...routeRoot.split("/"));
+}
+function shouldExcludeRoute(excludes, routePath, relativeFile, relativeDir) {
+	if (excludes.length === 0) return false;
+	const normalizedRoutePath = normalizeExcludeMatcher(routePath);
+	const candidates = new Set([
+		normalizedRoutePath,
+		normalizeExcludeMatcher(routePath.replace(/^\/+/, "")),
+		normalizeExcludeMatcher(relativeFile),
+		normalizeExcludeMatcher(relativeDir)
+	]);
+	return excludes.some((entry) => candidates.has(entry));
+}
+function humanizeSegment(value) {
+	return value.replace(/^\[\[?\.{3}/, "").replace(/^\[/, "").replace(/\]\]?$/, "").replace(/^\$/, "").replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function endpointSegmentFromFsSegment(value) {
+	if (value.startsWith("[[...") && value.endsWith("]]")) return `{${value.slice(5, -2)}}`;
+	if (value.startsWith("[...") && value.endsWith("]")) return `{${value.slice(4, -1)}}`;
+	if (value.startsWith("[") && value.endsWith("]")) return `{${value.slice(1, -1)}}`;
+	return value;
+}
+function getPathParamName(value) {
+	if (value.startsWith("[[...") && value.endsWith("]]")) return value.slice(5, -2);
+	if (value.startsWith("[...") && value.endsWith("]")) return value.slice(4, -1);
+	if (value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1);
+}
+function extractDocBlock(source) {
+	const match = source.match(/\/\*\*([\s\S]*?)\*\//);
+	if (!match) return {};
+	const lines = match[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter(Boolean).filter((line) => !line.startsWith("@"));
+	if (lines.length === 0) return {};
+	return {
+		summary: lines[0],
+		description: lines.slice(1).join(" ")
+	};
+}
+function extractMethods(source) {
+	const methods = /* @__PURE__ */ new Set();
+	for (const match of source.matchAll(METHOD_RE)) methods.add(match[1]);
+	return Array.from(methods);
+}
+function scanRouteFiles(dir) {
+	if (!existsSync(dir)) return [];
+	const results = [];
+	for (const name of readdirSync(dir)) {
+		const full = join(dir, name);
+		if (statSync(full).isDirectory()) {
+			results.push(...scanRouteFiles(full));
+			continue;
+		}
+		if (ROUTE_FILE_RE.test(name)) results.push(full);
+	}
+	return results;
+}
+function getDocsUrl(config) {
+	if (typeof config.nav?.url === "string") return config.nav.url;
+	return `/${config.entry ?? "docs"}`;
+}
+function getForcedMode(config) {
+	const toggle = config.themeToggle;
+	if (!toggle || typeof toggle !== "object") return void 0;
+	if (toggle.default === "dark") return "dark";
+	if (toggle.default === "light") return "light";
+}
+function isThemeToggleHidden(config) {
+	if (config.themeToggle === false) return true;
+	if (config.themeToggle && typeof config.themeToggle === "object") return config.themeToggle.enabled === false;
+	return false;
+}
+function buildPathParameters(fsSegments) {
+	const parameters = [];
+	for (const segment of fsSegments) {
+		const name = getPathParamName(segment);
+		if (!name) continue;
+		const optional = segment.startsWith("[[...");
+		parameters.push({
+			name,
+			in: "path",
+			required: !optional,
+			description: optional ? `${humanizeSegment(name)} catch-all parameter.` : `${humanizeSegment(name)} path parameter.`,
+			schema: { type: "string" }
+		});
+	}
+	return parameters;
+}
+function buildApiReferenceRoutes(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return [];
+	const root = process.cwd();
+	const apiDir = resolveNextApiRouteRoot(root, apiReference);
+	const routePathBase = getRoutePathBase(apiReference);
+	const files = scanRouteFiles(apiDir);
+	const excludes = apiReference.exclude;
+	const routes = [];
+	for (const file of files) {
+		const source = readFileSync(file, "utf-8");
+		const methods = extractMethods(source);
+		if (methods.length === 0) continue;
+		const relativeFile = relative(apiDir, file).replace(/\\/g, "/");
+		const fsSegments = relativeFile.split("/").slice(0, -1).filter(Boolean);
+		const relativeDir = fsSegments.join("/");
+		const routeSegments = fsSegments.map(endpointSegmentFromFsSegment);
+		const routePath = `${routePathBase}${routeSegments.length > 0 ? `/${routeSegments.join("/")}` : ""}` || "/";
+		if (shouldExcludeRoute(excludes, routePath, relativeFile, relativeDir)) continue;
+		const docBlock = extractDocBlock(source);
+		const title = fsSegments.length > 0 ? humanizeSegment(fsSegments[fsSegments.length - 1]) : "Overview";
+		routes.push({
+			title,
+			summary: docBlock.summary ?? `${title} endpoint`,
+			description: docBlock.description,
+			routePath,
+			sourceFile: relative(root, file).replace(/\\/g, "/"),
+			methods,
+			segments: fsSegments,
+			tag: fsSegments.length > 0 ? humanizeSegment(fsSegments[0]) : "General",
+			parameters: buildPathParameters(fsSegments)
+		});
+	}
+	return routes.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+function createOperationId(route, method) {
+	return `${method.toLowerCase()}_${route.routePath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+function buildRequestBody(method) {
+	if (![
+		"POST",
+		"PUT",
+		"PATCH"
+	].includes(method)) return void 0;
+	return {
+		required: method === "POST",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { example: true }
+		} }
+	};
+}
+function buildResponses(method) {
+	return { "200": {
+		description: method === "DELETE" ? "Resource removed successfully." : "Request completed successfully.",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { ok: true }
+		} }
+	} };
+}
+function buildOpenApiPaths(routes) {
+	const paths = {};
+	for (const route of routes) {
+		const pathItem = {};
+		for (const method of route.methods) pathItem[method.toLowerCase()] = {
+			tags: [route.tag],
+			summary: route.summary,
+			description: route.description ?? route.summary,
+			operationId: createOperationId(route, method),
+			...route.parameters.length > 0 ? { parameters: route.parameters } : {},
+			...buildRequestBody(method) ? { requestBody: buildRequestBody(method) } : {},
+			responses: buildResponses(method),
+			"x-farming-labs-source": route.sourceFile
+		};
+		paths[route.routePath] = pathItem;
+	}
+	return paths;
+}
+function buildNextOpenApiDocument(config) {
+	if (resolveApiReferenceConfig(config.apiReference).specUrl) return {
+		openapi: "3.1.0",
+		info: {
+			title: "API Reference",
+			description: "Remote OpenAPI specs are resolved at request time through createNextApiReference().",
+			version: "0.0.0"
+		},
+		servers: [{ url: "/" }],
+		tags: [],
+		paths: {}
+	};
+	const routes = buildApiReferenceRoutes(config);
+	const tags = Array.from(new Set(routes.map((route) => route.tag))).map((name) => ({
+		name,
+		description: `${name} endpoints`
+	}));
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "API Reference",
+			description: config.metadata?.description ?? "Generated API reference from Next.js route handlers.",
+			version: "0.0.0"
+		},
+		servers: [{ url: "/" }],
+		tags,
+		paths: buildOpenApiPaths(routes)
+	};
+}
+function DropdownIcon({ current, radius }) {
+	const label = current === "api" ? "</>" : "▣";
+	return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		style: {
+			display: "inline-flex",
+			width: 20,
+			height: 20,
+			alignItems: "center",
+			justifyContent: "center",
+			borderRadius: radius,
+			border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+			background: "color-mix(in srgb, var(--color-fd-card, #161616) 92%, transparent)",
+			color: "var(--color-fd-primary, currentColor)",
+			boxShadow: "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+			fontSize: 9,
+			fontWeight: 700
+		},
+		children: label
+	});
+}
+function getApiReferenceSwitcherTheme(config) {
+	const themeName = config.theme?.name?.toLowerCase() ?? "";
+	const isPixelBorder = themeName.includes("pixel-border");
+	const isDarksharp = themeName.includes("darksharp");
+	const isShiny = themeName.includes("shiny");
+	const radius = config.theme?.ui?.radius ?? (isPixelBorder || isDarksharp ? "0px" : "var(--radius, 0.75rem)");
+	return {
+		cardRadius: radius,
+		iconRadius: radius,
+		backgroundImage: isPixelBorder ? "repeating-linear-gradient(-45deg, color-mix(in srgb, var(--color-fd-border) 10%, transparent), color-mix(in srgb, var(--color-fd-border) 10%, transparent) 1px, transparent 1px, transparent 6px)" : void 0,
+		boxShadow: isPixelBorder || isDarksharp ? "none" : isShiny ? "0 14px 40px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 18%, transparent)" : "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+		titleStyle: {
+			fontFamily: isPixelBorder ? "var(--fd-font-mono, var(--font-geist-mono, ui-monospace, monospace))" : void 0,
+			textTransform: isPixelBorder ? "uppercase" : void 0,
+			letterSpacing: isPixelBorder ? "0.08em" : void 0,
+			fontSize: isPixelBorder ? 12 : 14
+		},
+		descriptionStyle: {
+			fontFamily: isPixelBorder ? "var(--fd-font-mono, var(--font-geist-mono, ui-monospace, monospace))" : void 0,
+			textTransform: isPixelBorder ? "uppercase" : void 0,
+			letterSpacing: isPixelBorder ? "0.04em" : void 0,
+			fontSize: isPixelBorder ? 11 : 12,
+			opacity: isPixelBorder ? .74 : .62
+		}
+	};
+}
+function SwitcherOption({ href, title, description, current, config }) {
+	const theme = getApiReferenceSwitcherTheme(config);
+	return /* @__PURE__ */ jsxs("a", {
+		href,
+		style: {
+			display: "grid",
+			gridTemplateColumns: "20px 1fr 14px",
+			gap: 12,
+			alignItems: "start",
+			padding: "11px 12px",
+			borderRadius: theme.cardRadius,
+			textDecoration: "none",
+			color: "inherit",
+			background: current ? "color-mix(in srgb, var(--color-fd-primary, #3a7) 10%, transparent)" : "transparent",
+			backgroundImage: !current ? theme.backgroundImage : void 0
+		},
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					display: "inline-flex",
+					width: 20,
+					height: 20,
+					alignItems: "center",
+					justifyContent: "center",
+					borderRadius: theme.iconRadius,
+					border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+					color: current ? "var(--color-fd-primary, currentColor)" : "var(--color-fd-muted-foreground, rgba(255,255,255,0.62))",
+					background: "color-mix(in srgb, var(--color-fd-card, #161616) 92%, transparent)",
+					boxShadow: "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+					fontSize: 9,
+					fontWeight: 700
+				},
+				children: title === "API Reference" ? "</>" : "▣"
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				style: {
+					display: "flex",
+					flexDirection: "column",
+					gap: 4
+				},
+				children: [/* @__PURE__ */ jsx("span", {
+					style: {
+						fontWeight: 600,
+						lineHeight: 1.25,
+						...theme.titleStyle
+					},
+					children: title
+				}), /* @__PURE__ */ jsx("span", {
+					style: {
+						lineHeight: 1.4,
+						...theme.descriptionStyle
+					},
+					children: description
+				})]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					fontSize: 12,
+					opacity: current ? 1 : 0,
+					color: "var(--color-fd-primary, currentColor)",
+					paddingTop: 2
+				},
+				children: "✓"
+			})
+		]
+	});
+}
+function ApiReferenceSwitcher({ docsUrl, apiUrl, current, config }) {
+	const currentLabel = current === "api" ? "API Reference" : "Documentation";
+	const theme = getApiReferenceSwitcherTheme(config);
+	return /* @__PURE__ */ jsxs("details", {
+		style: {
+			position: "relative",
+			marginBottom: 16,
+			borderRadius: theme.cardRadius,
+			border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+			background: "color-mix(in srgb, var(--color-fd-card, #141414) 94%, transparent)",
+			boxShadow: theme.boxShadow,
+			overflow: "hidden",
+			backgroundImage: theme.backgroundImage
+		},
+		children: [/* @__PURE__ */ jsxs("summary", {
+			style: {
+				listStyle: "none",
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "space-between",
+				gap: 10,
+				cursor: "pointer",
+				padding: "11px 13px",
+				background: "color-mix(in srgb, var(--color-fd-card, #202020) 96%, transparent)",
+				borderBottom: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)"
+			},
+			children: [/* @__PURE__ */ jsxs("span", {
+				style: {
+					display: "flex",
+					alignItems: "center",
+					gap: 10
+				},
+				children: [/* @__PURE__ */ jsx(DropdownIcon, {
+					current,
+					radius: theme.iconRadius
+				}), /* @__PURE__ */ jsx("span", {
+					style: {
+						fontWeight: 600,
+						...theme.titleStyle
+					},
+					children: currentLabel
+				})]
+			}), /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					fontSize: 11,
+					opacity: .56,
+					transform: "translateY(1px)"
+				},
+				children: "▿"
+			})]
+		}), /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				gap: 2,
+				padding: 8,
+				background: "color-mix(in srgb, var(--color-fd-card, #151515) 96%, transparent)"
+			},
+			children: [/* @__PURE__ */ jsx(SwitcherOption, {
+				href: docsUrl,
+				title: "Documentation",
+				description: "Markdown pages, guides, and concepts",
+				current: current === "docs",
+				config
+			}), /* @__PURE__ */ jsx(SwitcherOption, {
+				href: apiUrl,
+				title: "API Reference",
+				description: "Scalar-powered route handler reference",
+				current: current === "api",
+				config
+			})]
+		})]
+	});
+}
+function mergeBanner(existing, next) {
+	if (!existing) return next;
+	return /* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: 12
+		},
+		children: [existing, next]
+	});
+}
+function withNextApiReferenceBanner(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return config;
+	if (config.sidebar === false) return config;
+	const switcher = /* @__PURE__ */ jsx(ApiReferenceSwitcher, {
+		docsUrl: getDocsUrl(config),
+		apiUrl: `/${apiReference.path}`,
+		current: "docs",
+		config
+	});
+	if (!config.sidebar || config.sidebar === true) return {
+		...config,
+		sidebar: { banner: switcher }
+	};
+	return {
+		...config,
+		sidebar: {
+			...config.sidebar,
+			banner: mergeBanner(config.sidebar.banner, switcher)
+		}
+	};
+}
+function createNextApiReference(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	return async () => {
+		if (!apiReference.enabled) return new Response("Not Found", { status: 404 });
+		const document = await buildApiReferenceOpenApiDocumentAsync(config, {
+			framework: "next",
+			rootDir: process.cwd()
+		});
+		return ApiReference({
+			pageTitle: buildApiReferencePageTitle(config, "API Reference"),
+			title: "API Reference",
+			content: document,
+			theme: "deepSpace",
+			layout: "modern",
+			darkMode: getForcedMode(config) === "dark" ? true : void 0,
+			forceDarkModeState: getForcedMode(config),
+			hideDarkModeToggle: isThemeToggleHidden(config),
+			customCss: buildApiReferenceScalarCss(config),
+			pathRouting: { basePath: `/${apiReference.path}` },
+			showSidebar: true,
+			defaultOpenFirstTag: true,
+			tagsSorter: "alpha",
+			operationsSorter: "alpha",
+			operationTitleSource: "summary",
+			defaultHttpClient: {
+				targetKey: "shell",
+				clientKey: "curl"
+			},
+			documentDownloadType: "json"
+		})();
+	};
+}
+
+//#endregion
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner };

package/dist/client-callbacks.d.mts

@@ -0,0 +1,6 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/client-callbacks.d.ts
+declare function DocsClientCallbacks(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { DocsClientCallbacks as default };

package/dist/client-callbacks.mjs

@@ -0,0 +1,16 @@
+"use client";
+
+import { jsx } from "react/jsx-runtime";
+import docsConfig from "@farming-labs/next-internal-docs-config";
+import { DocsClientHooks } from "@farming-labs/theme/client-hooks";
+
+//#region src/client-callbacks.tsx
+function DocsClientCallbacks() {
+	return /* @__PURE__ */ jsx(DocsClientHooks, {
+		onCopyClick: docsConfig.onCopyClick,
+		onFeedback: docsConfig.feedback && typeof docsConfig.feedback === "object" ? docsConfig.feedback.onFeedback : void 0
+	});
+}
+
+//#endregion
+export { DocsClientCallbacks as default };

package/dist/config.d.mts

@@ -0,0 +1,28 @@
+import * as next from "next";
+
+//#region src/config.d.ts
+/**
+ * Next.js config wrapper for @farming-labs/docs.
+ * Handles MDX compilation, frontmatter, syntax highlighting, TOC extraction,
+ * and auto-generates mdx-components.tsx + docs layout when missing.
+ *
+ * @example
+ * // next.config.ts — this is all you need:
+ *   import { withDocs } from "@farming-labs/next/config";
+ *   export default withDocs();
+ *
+ * @example
+ * // With existing Next.js config
+ *   import { withDocs } from "@farming-labs/next/config";
+ *   export default withDocs({
+ *     images: { remotePatterns: [{ hostname: "example.com" }] },
+ *   });
+ *
+ * @example
+ * // Full static export (Cloudflare Pages, etc.) — no server; API route is skipped.
+ * // In docs.config set ai.enabled: false and staticExport: true.
+ *   export default withDocs({ output: "export" });
+ */
+declare function withDocs(nextConfig?: Record<string, unknown>): next.NextConfig;
+//#endregion
+export { withDocs };

package/dist/config.mjs

@@ -0,0 +1,322 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import createMDX from "@next/mdx";
+
+//#region src/config.ts
+/**
+* Next.js config wrapper for @farming-labs/docs.
+* Handles MDX compilation, frontmatter, syntax highlighting, TOC extraction,
+* and auto-generates mdx-components.tsx + docs layout when missing.
+*
+* @example
+* // next.config.ts — this is all you need:
+*   import { withDocs } from "@farming-labs/next/config";
+*   export default withDocs();
+*
+* @example
+* // With existing Next.js config
+*   import { withDocs } from "@farming-labs/next/config";
+*   export default withDocs({
+*     images: { remotePatterns: [{ hostname: "example.com" }] },
+*   });
+*
+* @example
+* // Full static export (Cloudflare Pages, etc.) — no server; API route is skipped.
+* // In docs.config set ai.enabled: false and staticExport: true.
+*   export default withDocs({ output: "export" });
+*/
+/** Resolve Next.js App Router directory: prefer src/app when present, else app. */
+function getNextAppDir(root) {
+	if (existsSync(join(root, "src", "app"))) return "src/app";
+	return "app";
+}
+const GENERATED_BANNER = "// Auto-generated by @farming-labs/next — do not edit manually.\n";
+const MDX_COMPONENTS_TEMPLATE = `\
+${GENERATED_BANNER}
+import { getMDXComponents } from "@farming-labs/theme/mdx";
+import type { MDXComponents } from "mdx/types";
+import docsConfig from "@/docs.config";
+
+export function useMDXComponents(components?: MDXComponents): MDXComponents {
+  return getMDXComponents(
+    {
+      ...(docsConfig.components as MDXComponents),
+      ...components,
+    },
+    {
+      onCopyClick: docsConfig.onCopyClick,
+      theme: docsConfig.theme,
+    },
+  );
+}
+`;
+const DOCS_LAYOUT_TEMPLATE = `\
+${GENERATED_BANNER}
+import docsConfig from "@/docs.config";
+import { createNextDocsLayout, createNextDocsMetadata } from "@farming-labs/next/layout";
+
+export const metadata = createNextDocsMetadata(docsConfig);
+
+const DocsLayout = createNextDocsLayout(docsConfig);
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <DocsLayout>{children}</DocsLayout>;
+}
+`;
+const DOCS_API_ROUTE_TEMPLATE = `\
+${GENERATED_BANNER}
+import docsConfig from "@/docs.config";
+import { createDocsAPI } from "@farming-labs/theme/api";
+
+export const { GET, POST } = createDocsAPI({
+  entry: docsConfig.entry,
+  i18n: docsConfig.i18n,
+});
+
+export const revalidate = false;
+`;
+const DOCS_MCP_ROUTE_TEMPLATE = `\
+${GENERATED_BANNER}
+import docsConfig from "@/docs.config";
+import { createDocsMCPAPI } from "@farming-labs/theme/api";
+
+export const { GET, POST, DELETE } = createDocsMCPAPI({
+  entry: docsConfig.entry,
+  contentDir: docsConfig.contentDir,
+  nav: docsConfig.nav,
+  ordering: docsConfig.ordering,
+  mcp: docsConfig.mcp,
+});
+
+export const revalidate = false;
+`;
+const API_REFERENCE_ROUTE_TEMPLATE = `\
+${GENERATED_BANNER}
+import docsConfig from "@/docs.config";
+import { createNextApiReference } from "@farming-labs/next/api-reference";
+
+export const GET = createNextApiReference(docsConfig);
+
+export const revalidate = false;
+`;
+const FILE_EXTS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+const INTERNAL_DOCS_CONFIG_ALIAS = "@farming-labs/next-internal-docs-config";
+function hasFile(root, baseName) {
+	return FILE_EXTS.some((ext) => existsSync(join(root, `${baseName}.${ext}`)));
+}
+function isManagedGeneratedFile(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		return readFileSync(filePath, "utf-8").startsWith(GENERATED_BANNER);
+	} catch {
+		return false;
+	}
+}
+/** Read the docs entry path from docs.config.ts[x] (defaults to "docs"). */
+function readDocsEntry(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = join(root, `docs.config.${ext}`);
+		if (existsSync(configPath)) try {
+			const match = readFileSync(configPath, "utf-8").match(/entry\s*:\s*["']([^"']+)["']/);
+			if (match) return match[1];
+		} catch {}
+	}
+	return "docs";
+}
+function readDocsConfigPath(root) {
+	for (const ext of FILE_EXTS) {
+		const relativePath = `docs.config.${ext}`;
+		if (existsSync(join(root, relativePath))) return relativePath;
+	}
+	return "docs.config.ts";
+}
+/** Read the OG endpoint from docs.config.ts[x] (returns undefined if not set). */
+function readOgEndpoint(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = join(root, `docs.config.${ext}`);
+		if (existsSync(configPath)) try {
+			const match = readFileSync(configPath, "utf-8").match(/endpoint\s*:\s*["']([^"']+)["']/);
+			if (match && match[1]) return match[1];
+		} catch {}
+	}
+}
+function readApiReferenceConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = join(root, `docs.config.${ext}`);
+		if (!existsSync(configPath)) continue;
+		try {
+			const content = readFileSync(configPath, "utf-8");
+			if (content.match(/apiReference\s*:\s*false/)) return {
+				enabled: false,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+			if (content.match(/apiReference\s*:\s*true/)) return {
+				enabled: true,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+			const block = extractObjectLiteral(content, "apiReference");
+			if (!block) continue;
+			const enabledMatch = block.match(/enabled\s*:\s*(true|false)/);
+			const pathMatch = block.match(/path\s*:\s*["']([^"']+)["']/);
+			const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
+			return {
+				enabled: enabledMatch ? enabledMatch[1] !== "false" : true,
+				path: pathMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api-reference",
+				routeRoot: routeRootMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api"
+			};
+		} catch {
+			return {
+				enabled: false,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+		}
+	}
+	return {
+		enabled: false,
+		path: "api-reference",
+		routeRoot: "api"
+	};
+}
+function extractObjectLiteral(content, key) {
+	const keyIndex = content.search(new RegExp(`${key}\\s*:\\s*\\{`));
+	if (keyIndex === -1) return void 0;
+	const braceStart = content.indexOf("{", keyIndex);
+	if (braceStart === -1) return void 0;
+	let depth = 0;
+	for (let index = braceStart; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return content.slice(braceStart + 1, index);
+	}
+}
+function readMcpConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = join(root, `docs.config.${ext}`);
+		if (!existsSync(configPath)) continue;
+		try {
+			const content = readFileSync(configPath, "utf-8");
+			if (content.match(/mcp\s*:\s*false/)) return {
+				enabled: false,
+				route: "/api/docs/mcp"
+			};
+			if (content.match(/mcp\s*:\s*true/)) return {
+				enabled: true,
+				route: "/api/docs/mcp"
+			};
+			const block = extractObjectLiteral(content, "mcp");
+			if (!block) continue;
+			const enabledMatch = block.match(/enabled\s*:\s*(true|false)/);
+			const routeMatch = block.match(/route\s*:\s*["']([^"']+)["']/);
+			return {
+				enabled: enabledMatch ? enabledMatch[1] !== "false" : true,
+				route: normalizeRoutePath(routeMatch?.[1] ?? "/api/docs/mcp")
+			};
+		} catch {
+			return {
+				enabled: false,
+				route: "/api/docs/mcp"
+			};
+		}
+	}
+	return {
+		enabled: false,
+		route: "/api/docs/mcp"
+	};
+}
+function normalizeRoutePath(route) {
+	const normalized = `/${route}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : "/api/docs/mcp";
+}
+function withDocs(nextConfig = {}) {
+	const root = process.cwd();
+	const docsConfigPath = readDocsConfigPath(root);
+	const docsConfigAbsolutePath = join(root, docsConfigPath);
+	const docsConfigRelativeAlias = docsConfigPath.startsWith("./") || docsConfigPath.startsWith("../") ? docsConfigPath : `./${docsConfigPath}`;
+	if (!hasFile(root, "mdx-components")) writeFileSync(join(root, "mdx-components.tsx"), MDX_COMPONENTS_TEMPLATE);
+	const entry = readDocsEntry(root);
+	const appDir = getNextAppDir(root);
+	const layoutDir = join(root, appDir, entry);
+	if (!existsSync(layoutDir)) mkdirSync(layoutDir, { recursive: true });
+	const docsLayoutPath = join(layoutDir, "layout.tsx");
+	if (!hasFile(layoutDir, "layout") || isManagedGeneratedFile(docsLayoutPath)) writeFileSync(join(layoutDir, "layout.tsx"), DOCS_LAYOUT_TEMPLATE);
+	const isStaticExport = nextConfig.output === "export";
+	const docsApiRouteDir = join(root, appDir, "api", "docs");
+	if (!isStaticExport && !hasFile(docsApiRouteDir, "route")) {
+		mkdirSync(docsApiRouteDir, { recursive: true });
+		writeFileSync(join(docsApiRouteDir, "route.ts"), DOCS_API_ROUTE_TEMPLATE);
+	}
+	const mcp = readMcpConfig(root);
+	const docsMcpRouteDir = join(root, appDir, "api", "docs", "mcp");
+	if (mcp.enabled && mcp.route === "/api/docs/mcp" && !isStaticExport && !hasFile(docsMcpRouteDir, "route")) {
+		mkdirSync(docsMcpRouteDir, { recursive: true });
+		writeFileSync(join(docsMcpRouteDir, "route.ts"), DOCS_MCP_ROUTE_TEMPLATE);
+	}
+	const apiReference = readApiReferenceConfig(root);
+	if (apiReference.enabled && !isStaticExport) {
+		const apiReferenceRouteDir = join(root, appDir, ...apiReference.path.split("/"), "[[...slug]]");
+		if (!hasFile(apiReferenceRouteDir, "route")) {
+			mkdirSync(apiReferenceRouteDir, { recursive: true });
+			writeFileSync(join(apiReferenceRouteDir, "route.ts"), API_REFERENCE_ROUTE_TEMPLATE);
+		}
+	}
+	const ogEndpoint = readOgEndpoint(root);
+	const remarkPlugins = ["remark-gfm", "remark-frontmatter"];
+	if (ogEndpoint) remarkPlugins.push(["@farming-labs/next/mdx-plugins/remark-og", { endpoint: ogEndpoint }]);
+	remarkPlugins.push(["remark-mdx-frontmatter", { name: "metadata" }], "@farming-labs/next/mdx-plugins/remark-heading");
+	const withMDX = createMDX({
+		extension: /\.mdx?$/,
+		options: {
+			remarkPlugins,
+			rehypePlugins: ["@farming-labs/next/mdx-plugins/rehype-toc", ["@farming-labs/next/mdx-plugins/rehype-code", { themes: {
+				dark: "github-dark",
+				light: "github-light"
+			} }]]
+		}
+	});
+	const defaultExts = [
+		"js",
+		"jsx",
+		"md",
+		"mdx",
+		"ts",
+		"tsx"
+	];
+	const userExts = nextConfig.pageExtensions;
+	if (userExts) {
+		for (const ext of ["md", "mdx"]) if (!userExts.includes(ext)) userExts.push(ext);
+	} else nextConfig.pageExtensions = defaultExts;
+	const existingTurbopack = nextConfig.turbopack ?? {};
+	const existingResolveAlias = existingTurbopack.resolveAlias ?? {};
+	nextConfig.turbopack = {
+		...existingTurbopack,
+		resolveAlias: {
+			...existingResolveAlias,
+			[INTERNAL_DOCS_CONFIG_ALIAS]: docsConfigRelativeAlias
+		}
+	};
+	const userWebpack = nextConfig.webpack;
+	nextConfig.webpack = (config, options) => {
+		const resolvedConfig = userWebpack ? userWebpack(config, options) : config;
+		resolvedConfig.resolve ??= {};
+		resolvedConfig.resolve.alias ??= {};
+		resolvedConfig.resolve.alias[INTERNAL_DOCS_CONFIG_ALIAS] = docsConfigAbsolutePath;
+		return resolvedConfig;
+	};
+	return withMDX(nextConfig);
+}
+
+//#endregion
+export { withDocs };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner } from "./api-reference.mjs";
+import { withDocs } from "./config.mjs";
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withDocs, withNextApiReferenceBanner };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { withDocs } from "./config.mjs";
+import { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner } from "./api-reference.mjs";
+
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withDocs, withNextApiReferenceBanner };

package/dist/layout.d.mts

@@ -0,0 +1,12 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { DocsConfig } from "@farming-labs/docs";
+
+//#region src/layout.d.ts
+declare function createNextDocsMetadata(config: DocsConfig): Record<string, unknown>;
+declare function createNextDocsLayout(config: DocsConfig): ({
+  children
+}: {
+  children: React.ReactNode;
+}) => react_jsx_runtime0.JSX.Element;
+//#endregion
+export { createNextDocsLayout, createNextDocsMetadata };

package/dist/layout.mjs

@@ -0,0 +1,18 @@
+import { withNextApiReferenceBanner } from "./api-reference.mjs";
+import DocsClientCallbacks from "./client-callbacks.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createDocsLayout, createDocsMetadata } from "@farming-labs/theme";
+
+//#region src/layout.tsx
+function createNextDocsMetadata(config) {
+	return createDocsMetadata(config);
+}
+function createNextDocsLayout(config) {
+	const DocsLayout = createDocsLayout(withNextApiReferenceBanner(config));
+	return function NextDocsLayout({ children }) {
+		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(DocsClientCallbacks, {}), /* @__PURE__ */ jsx(DocsLayout, { children })] });
+	};
+}
+
+//#endregion
+export { createNextDocsLayout, createNextDocsMetadata };

package/dist/mdx-plugins/rehype-code.d.mts

@@ -0,0 +1,2 @@
+import { rehypeCode as rehype_code_default } from "fumadocs-core/mdx-plugins/rehype-code";
+export { rehype_code_default as default };

package/dist/mdx-plugins/rehype-code.mjs

@@ -0,0 +1,3 @@
+import { rehypeCode as rehype_code_default } from "fumadocs-core/mdx-plugins/rehype-code";
+
+export { rehype_code_default as default };

package/dist/mdx-plugins/rehype-toc.d.mts

@@ -0,0 +1,2 @@
+import { rehypeToc as rehype_toc_default } from "fumadocs-core/mdx-plugins/rehype-toc";
+export { rehype_toc_default as default };

package/dist/mdx-plugins/rehype-toc.mjs

@@ -0,0 +1,3 @@
+import { rehypeToc as rehype_toc_default } from "fumadocs-core/mdx-plugins/rehype-toc";
+
+export { rehype_toc_default as default };

package/dist/mdx-plugins/remark-heading.d.mts

@@ -0,0 +1,2 @@
+import { remarkHeading as remark_heading_default } from "fumadocs-core/mdx-plugins/remark-heading";
+export { remark_heading_default as default };

package/dist/mdx-plugins/remark-heading.mjs

@@ -0,0 +1,3 @@
+import { remarkHeading as remark_heading_default } from "fumadocs-core/mdx-plugins/remark-heading";
+
+export { remark_heading_default as default };

package/dist/mdx-plugins/remark-og.d.mts

@@ -0,0 +1,22 @@
+//#region src/mdx-plugins/remark-og.d.ts
+/**
+ * Remark plugin that augments frontmatter with Open Graph metadata.
+ *
+ * Runs between remark-frontmatter and remark-mdx-frontmatter.
+ * Reads title/description from the YAML node and appends openGraph + twitter
+ * fields so that remark-mdx-frontmatter exports them as part of `metadata`.
+ *
+ * Skips injection when frontmatter already has `openGraph:` or `ogImage:`, so
+ * pages can use static OG images from frontmatter instead of the dynamic endpoint.
+ */
+interface RemarkOgOptions {
+  endpoint?: string;
+}
+declare function remarkOg(options?: RemarkOgOptions): (tree: {
+  children: Array<{
+    type: string;
+    value: string;
+  }>;
+}) => void;
+//#endregion
+export { remarkOg as default };

package/dist/mdx-plugins/remark-og.mjs

@@ -0,0 +1,30 @@
+//#region src/mdx-plugins/remark-og.ts
+function extractField(yaml, key) {
+	const re = new RegExp(`^${key}:\\s*(?:"([^"]*?)"|'([^']*?)'|(.+?))\\s*$`, "m");
+	const m = yaml.match(re);
+	return m?.[1] ?? m?.[2] ?? m?.[3];
+}
+/** True if the YAML already defines openGraph or ogImage (static OG). */
+function hasStaticOg(yaml) {
+	return /^\s*openGraph\s*:/m.test(yaml) || /^\s*ogImage\s*:/m.test(yaml);
+}
+function remarkOg(options = {}) {
+	const { endpoint = "/api/og" } = options;
+	return (tree) => {
+		const yamlNode = tree.children.find((n) => n.type === "yaml");
+		if (!yamlNode) return;
+		if (hasStaticOg(yamlNode.value)) return;
+		const title = extractField(yamlNode.value, "title");
+		if (!title) return;
+		const description = extractField(yamlNode.value, "description");
+		const params = new URLSearchParams({ title });
+		if (description) params.set("description", description);
+		const ogUrl = `${endpoint}?${params.toString()}`;
+		yamlNode.value += `
+openGraph:
+  images:\n    - url: "${ogUrl}"\n      width: 1200\n      height: 630\ntwitter:\n  card: "summary_large_image"\n  images:\n    - "${ogUrl}"`;
+	};
+}
+
+//#endregion
+export { remarkOg as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/next",
-  "version": "0.1.1-beta.4",
+  "version": "0.1.2",
   "description": "Next.js adapter for @farming-labs/docs — MDX config wrapper",
   "keywords": [
     "docs",
@@ -79,8 +79,8 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.1-beta.4",
-    "@farming-labs/theme": "0.1.1-beta.4"
+    "@farming-labs/docs": "0.1.2",
+    "@farming-labs/theme": "0.1.2"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",