@farming-labs/next 0.2.115 → 0.2.117

package/dist/api-reference.d.mts

@@ -34,8 +34,13 @@ declare function createNextApiReferencePage(config: DocsConfig): (props?: {
 }) => Promise<react_jsx_runtime0.JSX.Element>;
 declare function createNextApiReferenceLayout(config: DocsConfig): (props: {
   children: React.ReactNode;
+  params?: Promise<{
+    slug?: string[];
+  }> | {
+    slug?: string[];
+  };
 }) => Promise<react_jsx_runtime0.JSX.Element>;
-declare function getNextApiReferenceSourceState(config: DocsConfig): Promise<NextApiReferenceSourceState>;
-declare function getNextApiReferenceMode(config: DocsConfig): "fumadocs" | "scalar";
+declare function getNextApiReferenceSourceState(config: DocsConfig, versionId?: string): Promise<NextApiReferenceSourceState>;
+declare function getNextApiReferenceMode(config: DocsConfig): "farming-labs" | "fumadocs" | "scalar";
 //#endregion
 export { NextApiReferenceSourceState, buildNextOpenApiDocument, createNextApiReference, createNextApiReferenceLayout, createNextApiReferencePage, flattenApiReferencePageTreeForSidebar, getNextApiReferenceMode, getNextApiReferenceSourceState, resolveApiReferenceConfig, withNextApiReferenceBanner };

package/dist/api-reference.mjs

@@ -1,7 +1,8 @@
 import DocsClientCallbacks from "./client-callbacks.mjs";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, resolveApiReferenceConfig, resolveApiReferenceRenderer } from "@farming-labs/docs/server";
+import { resolveDocsMetadataBaseUrl } from "@farming-labs/docs";
+import { buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, createApiReferenceOperationMarkdownResponse, resolveApiReferenceConfig, resolveApiReferenceRenderer, resolveApiReferenceVersion, resolveApiReferenceVersionFromPathname } from "@farming-labs/docs/server";
 import { ApiReference } from "@scalar/nextjs-api-reference";
 import { SidebarTabsDropdown } from "fumadocs-ui/components/sidebar/tabs/dropdown";
 import Link from "next/link";
@@ -235,11 +236,12 @@ function buildOpenApiPaths(routes) {
 	return paths;
 }
 function buildNextOpenApiDocument(config) {
-	if (resolveApiReferenceConfig(config.apiReference).specUrl) return {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (apiReference.specUrl || apiReference.versions.length > 0) return {
 		openapi: "3.1.0",
 		info: {
 			title: "API Reference",
-			description: "Remote OpenAPI specs are resolved at request time through the Next.js API reference renderer.",
+			description: "Configured OpenAPI specs are resolved at request time through the Next.js API reference renderer.",
 			version: "0.0.0"
 		},
 		servers: [{ url: "/" }],
@@ -552,14 +554,39 @@ function createNextApiReference(config) {
 	const apiReference = resolveApiReferenceConfig(config.apiReference);
 	return async (request) => {
 		if (!apiReference.enabled) return new Response("Not Found", { status: 404 });
+		const requestUrl = request ? new URL(request.url) : void 0;
+		if (request && requestUrl) {
+			const markdownResponse = await createApiReferenceOperationMarkdownResponse(config, {
+				request,
+				framework: "next",
+				rootDir: process.cwd(),
+				baseUrl: getOriginFromRequest(request),
+				origin: resolveDocsMetadataBaseUrl(config) || getOriginFromRequest(request),
+				sitemap: config.sitemap,
+				okf: config.agent?.okf
+			});
+			if (markdownResponse) return markdownResponse;
+		}
+		const version = (requestUrl ? resolveApiReferenceVersionFromPathname(config.apiReference, requestUrl.pathname) : void 0) ?? resolveApiReferenceVersion(apiReference);
+		if (resolveApiReferenceRenderer(config.apiReference, "next") === "farming-labs") {
+			const html = await buildApiReferenceHtmlDocumentAsync(config, {
+				framework: "next",
+				rootDir: process.cwd(),
+				baseUrl: getOriginFromRequest(request),
+				version: version?.id
+			});
+			return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+		}
 		const document = await buildApiReferenceOpenApiDocumentAsync(config, {
 			framework: "next",
 			rootDir: process.cwd(),
-			baseUrl: getOriginFromRequest(request)
+			baseUrl: getOriginFromRequest(request),
+			version: version?.id
 		});
+		const basePath = `/${apiReference.path}${version ? `/${encodeURIComponent(version.id)}` : ""}`;
 		return ApiReference({
-			pageTitle: buildApiReferencePageTitle(config, "API Reference"),
-			title: "API Reference",
+			pageTitle: buildApiReferencePageTitle(config, version ? `API Reference – ${version.label}` : "API Reference"),
+			title: version ? `API Reference – ${version.label}` : "API Reference",
 			content: document,
 			theme: "deepSpace",
 			layout: "modern",
@@ -567,7 +594,7 @@ function createNextApiReference(config) {
 			forceDarkModeState: getForcedMode(config),
 			hideDarkModeToggle: isThemeToggleHidden(config),
 			customCss: buildApiReferenceScalarCss(config),
-			pathRouting: { basePath: `/${apiReference.path}` },
+			pathRouting: { basePath },
 			showSidebar: true,
 			defaultOpenFirstTag: true,
 			tagsSorter: "alpha",
@@ -591,8 +618,10 @@ function getOpenApiInfo(document) {
 function createNextApiReferencePage(config) {
 	return async function NextApiReferencePage(props) {
 		const [{ createAPIPage }, { DocsDescription, DocsPage, DocsTitle }] = await Promise.all([import("fumadocs-openapi/ui"), import("fumadocs-ui/layouts/notebook/page")]);
-		const { info, pages, server, source } = await getNextApiReferenceSourceState(config);
 		const slug = (props?.params ? await props.params : void 0)?.slug ?? [];
+		const version = resolveApiReferenceVersion(resolveApiReferenceConfig(config.apiReference), slug[0]);
+		const pageSlug = version ? slug.slice(1) : slug;
+		const { info, pages, server, source } = await getNextApiReferenceSourceState(config, version?.id);
 		if (pages.length === 0) return /* @__PURE__ */ jsxs(DocsPage, {
 			full: true,
 			children: [
@@ -607,10 +636,10 @@ function createNextApiReferencePage(config) {
 				})
 			]
 		});
-		const page = slug.length === 0 ? pages[0] : source.getPage(slug);
+		const page = pageSlug.length === 0 ? pages[0] : source.getPage(pageSlug);
 		if (!page || typeof page.data?.getAPIPageProps !== "function") notFound();
 		const APIPage = createAPIPage(server, { content: { renderOperationLayout: renderApiReferenceOperationLayout } });
-		const currentPageIndex = slug.length === 0 ? 0 : pages.findIndex((entry) => entry.url === page.url);
+		const currentPageIndex = pageSlug.length === 0 ? 0 : pages.findIndex((entry) => entry.url === page.url);
 		const previousPage = currentPageIndex > 0 ? pages[currentPageIndex - 1] : void 0;
 		const nextPage = currentPageIndex >= 0 && currentPageIndex < pages.length - 1 ? pages[currentPageIndex + 1] : void 0;
 		return /* @__PURE__ */ jsxs(DocsPage, {
@@ -681,10 +710,12 @@ function createNextApiReferencePage(config) {
 function createNextApiReferenceLayout(config) {
 	return async function NextApiReferenceLayout(props) {
 		const { DocsLayout } = await import("fumadocs-ui/layouts/notebook");
-		const { apiReference, primaryServerUrl, source } = await getNextApiReferenceSourceState(config);
+		const resolvedParams = props.params ? await props.params : void 0;
+		const version = resolveApiReferenceVersion(resolveApiReferenceConfig(config.apiReference), resolvedParams?.slug?.[0]);
+		const { apiReference, primaryServerUrl, source } = await getNextApiReferenceSourceState(config, version?.id);
 		const sidebarTree = flattenApiReferencePageTreeForSidebar(source.getPageTree());
 		const docsUrl = getDocsUrl(config);
-		const apiUrl = `/${apiReference.path}`;
+		const apiUrl = `/${apiReference.path}${version ? `/${encodeURIComponent(version.id)}` : ""}`;
 		const themeSwitch = resolveApiReferenceThemeSwitch(config.themeToggle);
 		const themeStyle = resolveApiReferenceThemeStyle(config);
 		const banner = mergeBanner(getExistingSidebarBanner(config), /* @__PURE__ */ jsx(ApiReferenceSwitcher, {
@@ -714,14 +745,16 @@ function createNextApiReferenceLayout(config) {
 		});
 	};
 }
-async function getNextApiReferenceSourceState(config) {
+async function getNextApiReferenceSourceState(config, versionId) {
 	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	const version = resolveApiReferenceVersion(apiReference, versionId);
 	const [{ createOpenAPI, openapiPlugin, openapiSource }, { loader }] = await Promise.all([import("fumadocs-openapi/server"), import("fumadocs-core/source")]);
 	const baseUrl = await getOriginFromNextHeaders();
 	const document = await buildApiReferenceOpenApiDocumentAsync(config, {
 		framework: "next",
 		rootDir: process.cwd(),
-		baseUrl
+		baseUrl,
+		version: version?.id
 	});
 	const server = createOpenAPI({ input: async () => ({ main: document }) });
 	const info = getOpenApiInfo(document);
@@ -734,7 +767,7 @@ async function getNextApiReferenceSourceState(config) {
 			return slugifyApiReferencePageName(typeof operation?.summary === "string" && operation.summary.trim() ? operation.summary : typeof operation?.operationId === "string" && operation.operationId.trim() ? operation.operationId : `${output.item.method} ${output.item.path}`);
 		}
 	}), {
-		baseUrl: `/${apiReference.path}`,
+		baseUrl: `/${apiReference.path}${version ? `/${encodeURIComponent(version.id)}` : ""}`,
 		plugins: [openapiPlugin()]
 	});
 	return {

package/dist/config.mjs

@@ -717,32 +717,32 @@ function readApiReferenceConfig(root) {
 			if (content.match(/apiReference\s*:\s*false/)) return {
 				enabled: false,
 				path: "api-reference",
-				renderer: "fumadocs",
+				renderer: "farming-labs",
 				routeRoot: "api"
 			};
 			if (content.match(/apiReference\s*:\s*true/)) return {
 				enabled: true,
 				path: "api-reference",
-				renderer: "fumadocs",
+				renderer: "farming-labs",
 				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 rendererMatch = block.match(/renderer\s*:\s*["'](fumadocs|scalar)["']/);
+			const rendererMatch = block.match(/renderer\s*:\s*["'](farming-labs|fumadocs|scalar)["']/);
 			const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
 			return {
 				enabled: enabledMatch ? enabledMatch[1] !== "false" : true,
 				path: pathMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api-reference",
-				renderer: rendererMatch?.[1] ?? "fumadocs",
+				renderer: rendererMatch?.[1] ?? "farming-labs",
 				routeRoot: routeRootMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api"
 			};
 		} catch {
 			return {
 				enabled: false,
 				path: "api-reference",
-				renderer: "fumadocs",
+				renderer: "farming-labs",
 				routeRoot: "api"
 			};
 		}
@@ -750,7 +750,7 @@ function readApiReferenceConfig(root) {
 	return {
 		enabled: false,
 		path: "api-reference",
-		renderer: "fumadocs",
+		renderer: "farming-labs",
 		routeRoot: "api"
 	};
 }
@@ -1601,6 +1601,72 @@ function buildDocsMarkdownRewrites(entry, docsPath) {
 		}
 	];
 }
+function buildApiReferenceMarkdownRewrites(apiReference) {
+	if (!apiReference.enabled) return [];
+	const basePath = `/${apiReference.path}`;
+	const markdownAcceptHeader = {
+		type: "header",
+		key: "accept",
+		value: MARKDOWN_ACCEPT_HEADER_VALUE
+	};
+	const markdownSignatureAgentHeader = {
+		type: "header",
+		key: "signature-agent",
+		value: ".+"
+	};
+	const markdownAgentUserAgentHeader = {
+		type: "header",
+		key: "user-agent",
+		value: DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN
+	};
+	const markdownBotLikeUserAgentHeader = {
+		type: "header",
+		key: "user-agent",
+		value: DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN
+	};
+	const markdownTraditionalBotUserAgentHeader = {
+		type: "header",
+		key: "user-agent",
+		value: DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN
+	};
+	const markdownSecFetchModeHeader = {
+		type: "header",
+		key: "sec-fetch-mode"
+	};
+	return [{
+		source: `${basePath}/operations/:operation`,
+		path: `${apiReference.path}/operations/:operation`
+	}, {
+		source: `${basePath}/:version/operations/:operation`,
+		path: `${apiReference.path}/:version/operations/:operation`
+	}].flatMap((route) => [
+		{
+			source: `${route.source}.md`,
+			destination: `/api/docs?format=markdown&path=${route.path}`
+		},
+		{
+			source: route.source,
+			has: [markdownAcceptHeader],
+			destination: `/api/docs?format=markdown&path=${route.path}`
+		},
+		{
+			source: route.source,
+			has: [markdownSignatureAgentHeader],
+			destination: `/api/docs?format=markdown&path=${route.path}`
+		},
+		{
+			source: route.source,
+			has: [markdownAgentUserAgentHeader],
+			destination: `/api/docs?format=markdown&path=${route.path}`
+		},
+		{
+			source: route.source,
+			has: [markdownBotLikeUserAgentHeader],
+			missing: [markdownTraditionalBotUserAgentHeader, markdownSecFetchModeHeader],
+			destination: `/api/docs?format=markdown&path=${route.path}`
+		}
+	]);
+}
 function buildAgentSpecRewrites() {
 	return [
 		{
@@ -1907,7 +1973,7 @@ function buildHiddenFolderRedirects(docsDir, docsPath) {
 	scan(docsDir, []);
 	return dedupeRedirects(redirects);
 }
-function mergeDocsMarkdownRewrites(entry, docsPath, mcp, sitemap, agentFeedback, robots, result) {
+function mergeDocsMarkdownRewrites(entry, docsPath, apiReference, mcp, sitemap, agentFeedback, robots, result) {
 	const autoBeforeFilesRewrites = [
 		...buildAgentSpecRewrites(),
 		...buildStandardsDiscoveryRewrites(),
@@ -1917,6 +1983,7 @@ function mergeDocsMarkdownRewrites(entry, docsPath, mcp, sitemap, agentFeedback,
 		...buildSitemapRewrites(sitemap),
 		...buildRobotsRewrites(robots),
 		...buildDocsMarkdownRewrites(entry, docsPath),
+		...buildApiReferenceMarkdownRewrites(apiReference),
 		...buildDocsPathRewrites(entry, docsPath),
 		...buildAgentFeedbackRewrites(agentFeedback)
 	];
@@ -2147,7 +2214,7 @@ function withDocs(nextConfig = {}, docsConfig) {
 	if (!isStaticExport) {
 		const existingRewrites = nextConfig.rewrites;
 		nextConfig.rewrites = async () => {
-			return mergeDocsMarkdownRewrites(entry, docsPath, mcp, sitemap, agentFeedback, robots, typeof existingRewrites === "function" ? await existingRewrites() : existingRewrites);
+			return mergeDocsMarkdownRewrites(entry, docsPath, apiReference, mcp, sitemap, agentFeedback, robots, typeof existingRewrites === "function" ? await existingRewrites() : existingRewrites);
 		};
 		const autoRedirects = buildHiddenFolderRedirects(docsContentRoot, docsPath);
 		if (autoRedirects.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/next",
-  "version": "0.2.115",
+  "version": "0.2.117",
   "description": "Next.js adapter for @farming-labs/docs — MDX config wrapper",
   "keywords": [
     "docs",
@@ -109,8 +109,8 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/docs": "0.2.115",
-    "@farming-labs/theme": "0.2.115"
+    "@farming-labs/theme": "0.2.117",
+    "@farming-labs/docs": "0.2.117"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.2.73",