@farming-labs/docs 0.0.2-beta.15 → 0.0.2-beta.17

package/dist/cli/index.mjs

@@ -17,6 +17,7 @@ function detectFramework(cwd) {
 	if (allDeps["next"]) return "nextjs";
 	if (allDeps["@sveltejs/kit"]) return "sveltekit";
 	if (allDeps["astro"]) return "astro";
+	if (allDeps["nuxt"]) return "nuxt";
 	return null;
 }
 function detectPackageManager(cwd) {
@@ -66,7 +67,9 @@ const GLOBAL_CSS_CANDIDATES = [
 	"styles/globals.css",
 	"styles/global.css",
 	"src/styles/globals.css",
-	"src/styles/global.css"
+	"src/styles/global.css",
+	"assets/css/main.css",
+	"assets/main.css"
 ];
 /**
 * Find existing global CSS files in the project.
@@ -135,27 +138,44 @@ const THEME_INFO = {
 		nextImport: "@farming-labs/theme",
 		svelteImport: "@farming-labs/svelte-theme",
 		astroImport: "@farming-labs/astro-theme",
+		nuxtImport: "@farming-labs/nuxt-theme",
 		nextCssImport: "default",
 		svelteCssTheme: "fumadocs",
-		astroCssTheme: "fumadocs"
+		astroCssTheme: "fumadocs",
+		nuxtCssTheme: "fumadocs"
 	},
 	darksharp: {
 		factory: "darksharp",
 		nextImport: "@farming-labs/theme/darksharp",
 		svelteImport: "@farming-labs/svelte-theme/darksharp",
 		astroImport: "@farming-labs/astro-theme/darksharp",
+		nuxtImport: "@farming-labs/nuxt-theme/darksharp",
 		nextCssImport: "darksharp",
 		svelteCssTheme: "darksharp",
-		astroCssTheme: "darksharp"
+		astroCssTheme: "darksharp",
+		nuxtCssTheme: "darksharp"
 	},
 	"pixel-border": {
 		factory: "pixelBorder",
 		nextImport: "@farming-labs/theme/pixel-border",
 		svelteImport: "@farming-labs/svelte-theme/pixel-border",
 		astroImport: "@farming-labs/astro-theme/pixel-border",
+		nuxtImport: "@farming-labs/nuxt-theme/pixel-border",
 		nextCssImport: "pixel-border",
 		svelteCssTheme: "pixel-border",
-		astroCssTheme: "pixel-border"
+		astroCssTheme: "pixel-border",
+		nuxtCssTheme: "pixel-border"
+	},
+	colorful: {
+		factory: "colorful",
+		nextImport: "@farming-labs/theme/colorful",
+		svelteImport: "@farming-labs/svelte-theme/colorful",
+		astroImport: "@farming-labs/astro-theme/colorful",
+		nuxtImport: "@farming-labs/nuxt-theme/colorful",
+		nextCssImport: "colorful",
+		svelteCssTheme: "colorful",
+		astroCssTheme: "colorful",
+		nuxtCssTheme: "colorful"
 	}
 };
 function getThemeInfo(theme) {
@@ -1107,6 +1127,322 @@ pnpm build
 Deploy to Vercel, Netlify, or any Node.js hosting platform.
 `;
 }
+function nuxtDocsConfigTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	return `\
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.nuxtImport}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${t.factory}({
+    ui: {
+      colors: { primary: "#6366f1" },
+    },
+  }),
+
+  nav: {
+    title: "${cfg.projectName}",
+    url: "/${cfg.entry}",
+  },
+
+  breadcrumb: { enabled: true },
+
+  metadata: {
+    titleTemplate: "%s – ${cfg.projectName}",
+    description: "Documentation for ${cfg.projectName}",
+  },
+});
+`;
+}
+function nuxtDocsServerTemplate(cfg) {
+	return `\
+import { createDocsServer } from "@farming-labs/nuxt/server";
+import config from "../../docs.config";
+
+const contentFiles = import.meta.glob("/${cfg.entry ?? "docs"}/**/*.{md,mdx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+export const docsServer = createDocsServer({
+  ...config,
+  _preloadedContent: contentFiles,
+});
+`;
+}
+function nuxtServerApiDocsGetTemplate() {
+	return `\
+import { getRequestURL } from "h3";
+import { docsServer } from "../utils/docs-server";
+
+export default defineEventHandler((event) => {
+  const url = getRequestURL(event);
+  const request = new Request(url.href, {
+    method: event.method,
+    headers: event.headers,
+  });
+  return docsServer.GET({ request });
+});
+`;
+}
+function nuxtServerApiDocsPostTemplate() {
+	return `\
+import { getRequestURL, readRawBody } from "h3";
+import { docsServer } from "../utils/docs-server";
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+  const body = await readRawBody(event);
+  const request = new Request(url.href, {
+    method: "POST",
+    headers: event.headers,
+    body: body ?? undefined,
+  });
+  return docsServer.POST({ request });
+});
+`;
+}
+function nuxtServerApiDocsLoadTemplate() {
+	return `\
+import { getQuery } from "h3";
+import { docsServer } from "../../utils/docs-server";
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event);
+  const pathname = (query.pathname as string) ?? "/docs";
+  return docsServer.load(pathname);
+});
+`;
+}
+function nuxtDocsPageTemplate(cfg) {
+	return `\
+<script setup lang="ts">
+import { DocsLayout, DocsContent } from "@farming-labs/nuxt-theme";
+import config from "${cfg.useAlias ? "~/docs.config" : "../../docs.config"}";
+
+const route = useRoute();
+const pathname = computed(() => route.path);
+
+const { data, error } = await useAsyncData(\`docs-\${pathname.value}\`, () =>
+  $fetch("/api/docs/load", {
+    query: { pathname: pathname.value },
+  })
+);
+
+if (error.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: "Page not found",
+  });
+}
+<\/script>
+
+<template>
+  <div v-if="data" class="fd-docs-wrapper">
+    <DocsLayout :tree="data.tree" :config="config">
+      <DocsContent :data="data" :config="config" />
+    </DocsLayout>
+  </div>
+</template>
+`;
+}
+function nuxtConfigTemplate(cfg) {
+	return `\
+export default defineNuxtConfig({
+  compatibilityDate: "2024-11-01",
+
+  css: ["@farming-labs/nuxt-theme/${getThemeInfo(cfg.theme).nuxtCssTheme}/css"],
+
+  vite: {
+    optimizeDeps: {
+      include: ["@farming-labs/docs", "@farming-labs/nuxt", "@farming-labs/nuxt-theme"],
+    },
+  },
+
+  nitro: {
+    moduleSideEffects: ["@farming-labs/nuxt/server"],
+  },
+});
+`;
+}
+function nuxtWelcomePageTemplate(cfg) {
+	return `\
+---
+order: 1
+title: Documentation
+description: Welcome to ${cfg.projectName} documentation
+icon: book
+---
+
+# Welcome to ${cfg.projectName}
+
+Get started with our documentation. Browse the pages on the left to learn more.
+
+## Overview
+
+This documentation was generated by \`@farming-labs/docs\`. Edit the markdown files in \`${cfg.entry}/\` to customize.
+
+## Features
+
+- **Markdown Support** — Write docs with standard Markdown
+- **Syntax Highlighting** — Code blocks with automatic highlighting
+- **Dark Mode** — Built-in theme switching
+- **Search** — Full-text search across all pages (⌘K)
+- **Responsive** — Works on any screen size
+
+---
+
+## Next Steps
+
+Start by reading the [Installation](/${cfg.entry}/installation) guide, then follow the [Quickstart](/${cfg.entry}/quickstart) to build something.
+`;
+}
+function nuxtInstallationPageTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	return `\
+---
+order: 3
+title: Installation
+description: How to install and set up ${cfg.projectName}
+icon: terminal
+---
+
+# Installation
+
+Follow these steps to install and configure ${cfg.projectName}.
+
+## Prerequisites
+
+- Node.js 18+
+- A package manager (pnpm, npm, or yarn)
+
+## Install Dependencies
+
+\`\`\`bash
+pnpm add @farming-labs/docs @farming-labs/nuxt @farming-labs/nuxt-theme
+\`\`\`
+
+## Configuration
+
+Your project includes a \`docs.config.ts\` at the root:
+
+\`\`\`ts title="docs.config.ts"
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.nuxtImport}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${t.factory}({
+    ui: { colors: { primary: "#6366f1" } },
+  }),
+});
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+${cfg.entry}/                   # Markdown content
+  page.md
+  installation/page.md
+  quickstart/page.md
+server/
+  utils/docs-server.ts          # createDocsServer + preloaded content
+  api/docs/
+    load.get.ts                 # Page data API
+    docs.get.ts                 # Search API
+    docs.post.ts                # AI chat API
+pages/
+  ${cfg.entry}/[[...slug]].vue   # Docs catch-all page
+docs.config.ts
+nuxt.config.ts
+\`\`\`
+
+## What's Next?
+
+Head to the [Quickstart](/${cfg.entry}/quickstart) guide to start writing your first page.
+`;
+}
+function nuxtQuickstartPageTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	return `\
+---
+order: 2
+title: Quickstart
+description: Get up and running in minutes
+icon: rocket
+---
+
+# Quickstart
+
+This guide walks you through creating your first documentation page.
+
+## Creating a Page
+
+Create a new folder under \`${cfg.entry}/\` with a \`page.md\` file:
+
+\`\`\`bash
+mkdir -p ${cfg.entry}/my-page
+\`\`\`
+
+Then create \`${cfg.entry}/my-page/page.md\`:
+
+\`\`\`md
+---
+title: "My Page"
+description: "A custom documentation page"
+---
+
+# My Page
+
+Write your content here using **Markdown**.
+\`\`\`
+
+Your page is now available at \`/${cfg.entry}/my-page\`.
+
+## Customizing the Theme
+
+Edit \`docs.config.ts\` to change colors and typography:
+
+\`\`\`ts
+theme: ${t.factory}({
+  ui: {
+    colors: { primary: "#22c55e" },
+  },
+}),
+\`\`\`
+
+## Deploying
+
+Build your docs for production:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
+Deploy to Vercel, Netlify, or any Node.js hosting platform.
+`;
+}
+function nuxtGlobalCssTemplate(theme) {
+	return `\
+@import "@farming-labs/nuxt-theme/${theme}/css";
+`;
+}
+function nuxtCssImportLine(theme) {
+	return `@import "@farming-labs/nuxt-theme/${theme}/css";`;
+}
+function injectNuxtCssImport(existingContent, theme) {
+	const importLine = nuxtCssImportLine(theme);
+	if (existingContent.includes(importLine)) return null;
+	const lines = existingContent.split("\n");
+	const lastImportIdx = lines.reduce((acc, l, i) => l.trimStart().startsWith("@import") ? i : acc, -1);
+	if (lastImportIdx >= 0) lines.splice(lastImportIdx + 1, 0, importLine);
+	else lines.unshift(importLine);
+	return lines.join("\n");
+}
 
 //#endregion
 //#region src/cli/init.ts
@@ -1115,7 +1451,7 @@ async function init() {
 	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
 	let framework = detectFramework(cwd);
 	if (framework) {
-		const frameworkName = framework === "nextjs" ? "Next.js" : framework === "sveltekit" ? "SvelteKit" : "Astro";
+		const frameworkName = framework === "nextjs" ? "Next.js" : framework === "sveltekit" ? "SvelteKit" : framework === "astro" ? "Astro" : "Nuxt";
 		p.log.success(`Detected framework: ${pc.cyan(frameworkName)}`);
 	} else {
 		p.log.warn("Could not auto-detect a framework from " + pc.cyan("package.json") + ".");
@@ -1136,6 +1472,11 @@ async function init() {
 					value: "astro",
 					label: "Astro",
 					hint: "Content-focused framework with island architecture"
+				},
+				{
+					value: "nuxt",
+					label: "Nuxt",
+					hint: "Vue 3 framework with file-based routing and Nitro server"
 				}
 			]
 		});
@@ -1162,6 +1503,11 @@ async function init() {
 				value: "pixel-border",
 				label: "Pixel Border",
 				hint: "Rounded borders, pixel-perfect spacing, refined sidebar"
+			},
+			{
+				value: "colorful",
+				label: "Colorful",
+				hint: "Fumadocs-style neutral theme with description support"
 			}
 		]
 	});
@@ -1169,7 +1515,7 @@ async function init() {
 		p.outro(pc.red("Init cancelled."));
 		process.exit(0);
 	}
-	const aliasHint = framework === "nextjs" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : framework === "sveltekit" ? `Uses ${pc.cyan("$lib/")} prefix (SvelteKit built-in)` : `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)`;
+	const aliasHint = framework === "nextjs" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : framework === "sveltekit" ? `Uses ${pc.cyan("$lib/")} prefix (SvelteKit built-in)` : framework === "nuxt" ? `Uses ${pc.cyan("~/")} prefix (Nuxt built-in)` : `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)`;
 	const useAlias = await p.confirm({
 		message: `Use path aliases for imports? ${pc.dim(aliasHint)}`,
 		initialValue: false
@@ -1226,7 +1572,7 @@ async function init() {
 	const entryPath = entry;
 	const detectedCssFiles = detectGlobalCssFiles(cwd);
 	let globalCssRelPath;
-	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : framework === "astro" ? "src/styles/global.css" : "app/globals.css";
+	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : framework === "astro" ? "src/styles/global.css" : framework === "nuxt" ? "assets/css/main.css" : "app/globals.css";
 	if (detectedCssFiles.length === 1) {
 		globalCssRelPath = detectedCssFiles[0];
 		p.log.info(`Found global CSS at ${pc.cyan(globalCssRelPath)}`);
@@ -1279,6 +1625,7 @@ async function init() {
 	}
 	if (framework === "sveltekit") scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written);
 	else if (framework === "astro") scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written);
+	else if (framework === "nuxt") scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written);
 	else scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written);
 	s.stop("Files scaffolded");
 	if (written.length > 0) p.log.success(`Created ${written.length} file${written.length > 1 ? "s" : ""}:\n` + written.map((f) => `  ${pc.green("+")} ${f}`).join("\n"));
@@ -1292,7 +1639,8 @@ async function init() {
 		else if (framework === "astro") {
 			const adapterPkg = getAstroAdapterPkg(cfg.astroAdapter ?? "vercel");
 			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/astro @farming-labs/astro-theme ${adapterPkg}`, cwd);
-		} else {
+		} else if (framework === "nuxt") exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/nuxt @farming-labs/nuxt-theme`, cwd);
+		else {
 			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/next @farming-labs/theme`, cwd);
 			const devDeps = [
 				"@tailwindcss/postcss",
@@ -1335,6 +1683,10 @@ async function init() {
 		cmd: "npx",
 		args: ["astro", "dev"],
 		waitFor: "ready"
+	} : framework === "nuxt" ? {
+		cmd: "npx",
+		args: ["nuxt", "dev"],
+		waitFor: "Local"
 	} : {
 		cmd: "npx",
 		args: [
@@ -1344,7 +1696,7 @@ async function init() {
 		],
 		waitFor: "Ready"
 	};
-	const defaultPort = framework === "sveltekit" ? "5173" : framework === "astro" ? "4321" : "3000";
+	const defaultPort = framework === "sveltekit" ? "5173" : framework === "astro" ? "4321" : framework === "nuxt" ? "3000" : "3000";
 	try {
 		const child = await spawnAndWaitFor(devCommand.cmd, devCommand.args, cwd, devCommand.waitFor, 6e4);
 		const url = `http://localhost:${defaultPort}/${entryPath}`;
@@ -1363,7 +1715,7 @@ async function init() {
 			});
 		});
 	} catch (err) {
-		const manualCmd = framework === "sveltekit" ? "npx vite dev" : framework === "astro" ? "npx astro dev" : "npx next dev --webpack";
+		const manualCmd = framework === "sveltekit" ? "npx vite dev" : framework === "astro" ? "npx astro dev" : framework === "nuxt" ? "npx nuxt dev" : "npx next dev --webpack";
 		p.log.error(`Could not start dev server. Try running manually:
   ${pc.cyan(manualCmd)}`);
 		p.outro(pc.yellow("Setup complete. Start the server manually."));
@@ -1411,6 +1763,7 @@ function scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written)
 		fumadocs: "fumadocs",
 		darksharp: "darksharp",
 		"pixel-border": "pixel-border",
+		colorful: "colorful",
 		default: "fumadocs"
 	}[cfg.theme] || "fumadocs";
 	if (existingGlobalCss) {
@@ -1437,6 +1790,7 @@ function scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written) {
 		fumadocs: "fumadocs",
 		darksharp: "darksharp",
 		"pixel-border": "pixel-border",
+		colorful: "colorful",
 		default: "fumadocs"
 	}[cfg.theme] || "fumadocs";
 	if (existingGlobalCss) {
@@ -1450,6 +1804,34 @@ function scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	write(`${cfg.entry}/installation/page.md`, astroInstallationPageTemplate(cfg));
 	write(`${cfg.entry}/quickstart/page.md`, astroQuickstartPageTemplate(cfg));
 }
+function scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written) {
+	write("docs.config.ts", nuxtDocsConfigTemplate(cfg));
+	write("server/utils/docs-server.ts", nuxtDocsServerTemplate(cfg));
+	write("server/api/docs.get.ts", nuxtServerApiDocsGetTemplate());
+	write("server/api/docs.post.ts", nuxtServerApiDocsPostTemplate());
+	write("server/api/docs/load.get.ts", nuxtServerApiDocsLoadTemplate());
+	write(`pages/${cfg.entry}/[[...slug]].vue`, nuxtDocsPageTemplate(cfg));
+	path.join(cwd, "nuxt.config.ts");
+	if (!fileExists(path.join(cwd, "nuxt.config.ts")) && !fileExists(path.join(cwd, "nuxt.config.js"))) write("nuxt.config.ts", nuxtConfigTemplate(cfg));
+	const cssTheme = {
+		fumadocs: "fumadocs",
+		darksharp: "darksharp",
+		"pixel-border": "pixel-border",
+		default: "fumadocs"
+	}[cfg.theme] || "fumadocs";
+	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
+	const existingGlobalCss = readFileSafe(globalCssAbsPath);
+	if (existingGlobalCss) {
+		const injected = injectNuxtCssImport(existingGlobalCss, cssTheme);
+		if (injected) {
+			writeFileSafe(globalCssAbsPath, injected, true);
+			written.push(globalCssRelPath + " (updated)");
+		} else skipped.push(globalCssRelPath + " (already configured)");
+	} else write(globalCssRelPath, nuxtGlobalCssTemplate(cssTheme));
+	write(`${cfg.entry}/page.md`, nuxtWelcomePageTemplate(cfg));
+	write(`${cfg.entry}/installation/page.md`, nuxtInstallationPageTemplate(cfg));
+	write(`${cfg.entry}/quickstart/page.md`, nuxtQuickstartPageTemplate(cfg));
+}
 
 //#endregion
 //#region src/cli/index.ts
@@ -1476,7 +1858,7 @@ ${pc.dim("Commands:")}
   ${pc.cyan("init")}    Scaffold docs in your project (default)
 
 ${pc.dim("Supported frameworks:")}
-  Next.js, SvelteKit, Astro
+  Next.js, SvelteKit, Astro, Nuxt
 
 ${pc.dim("Options:")}
   ${pc.cyan("-h, --help")}       Show this help message

package/dist/index.d.mts

@@ -137,6 +137,13 @@ interface UIConfig {
     toc?: {
       enabled?: boolean;
       depth?: number;
+      /**
+       * Visual style of the TOC indicator.
+       * - `"default"` — highlight active link text color only
+       * - `"directional"` — animated thumb bar that tracks active headings (fumadocs style)
+       * @default "default"
+       */
+      style?: "default" | "directional";
     };
     header?: {
       height?: number;
@@ -533,19 +540,44 @@ interface AIConfig {
    */
   floatingStyle?: "panel" | "modal" | "popover" | "full-modal";
   /**
-   * Custom trigger component for the floating chat button.
+   * Custom trigger component for the floating chat button (Next.js only).
    * Only used when `mode` is `"floating"`.
    *
-   * Pass a React element to replace the default sparkles button.
-   * The element receives an `onClick` handler automatically.
+   * The click handler is attached automatically by the wrapper.
+   *
+   * - **Next.js**: Pass a JSX element via this config option.
+   * - **SvelteKit**: Use the `aiTrigger` snippet on `<DocsLayout>`.
+   * - **Nuxt / Vue**: Use the `ai-trigger` slot on `<DocsLayout>`.
+   * - **Astro**: Use `<MyTrigger slot="ai-trigger" />` on `<DocsLayout>`.
    *
    * @example
    * ```tsx
-   * ai: {
-   *   enabled: true,
-   *   mode: "floating",
-   *   triggerComponent: <button className="my-chat-btn">💬 Help</button>,
-   * }
+   * // Next.js — pass JSX directly in config
+   * triggerComponent: <button className="my-chat-btn">Ask AI</button>,
+   * ```
+   *
+   * ```svelte
+   * <!-- SvelteKit — use snippet in layout -->
+   * <DocsLayout {tree} {config}>
+   *   {#snippet aiTrigger()}<AskAITrigger />{/snippet}
+   *   {@render children()}
+   * </DocsLayout>
+   * ```
+   *
+   * ```vue
+   * <!-- Nuxt / Vue — use named slot in layout -->
+   * <DocsLayout :tree="tree" :config="config">
+   *   <template #ai-trigger><AskAITrigger /></template>
+   *   <DocsContent />
+   * </DocsLayout>
+   * ```
+   *
+   * ```astro
+   * <!-- Astro — use named slot in layout -->
+   * <DocsLayout tree={tree} config={config}>
+   *   <AskAITrigger slot="ai-trigger" />
+   *   <DocsContent />
+   * </DocsLayout>
    * ```
    */
   triggerComponent?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.2-beta.15",
+  "version": "0.0.2-beta.17",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "type": "module",
   "main": "./dist/index.mjs",