@farming-labs/docs 0.0.2-beta.1

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli/index.mjs

@@ -0,0 +1,610 @@
+#!/usr/bin/env node
+import pc from "picocolors";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import fs from "node:fs";
+import { execSync, spawn } from "node:child_process";
+
+//#region src/cli/utils.ts
+function detectFramework(cwd) {
+	const pkgPath = path.join(cwd, "package.json");
+	if (!fs.existsSync(pkgPath)) return null;
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+	if ({
+		...pkg.dependencies,
+		...pkg.devDependencies
+	}["next"]) return "nextjs";
+	return null;
+}
+function detectPackageManager(cwd) {
+	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) return "bun";
+	if (fs.existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+	return "npm";
+}
+function installCommand(pm) {
+	return pm === "yarn" ? "yarn add" : `${pm} add`;
+}
+function devInstallCommand(pm) {
+	if (pm === "yarn") return "yarn add -D";
+	if (pm === "npm") return "npm install -D";
+	return `${pm} add -D`;
+}
+/**
+* Write a file, creating parent directories as needed.
+* Returns true if the file was written, false if it already existed and was skipped.
+*/
+function writeFileSafe(filePath, content, overwrite = false) {
+	if (fs.existsSync(filePath) && !overwrite) return false;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, content, "utf-8");
+	return true;
+}
+/**
+* Check if a file exists.
+*/
+function fileExists(filePath) {
+	return fs.existsSync(filePath);
+}
+/**
+* Read a file, returning null if it does not exist.
+*/
+function readFileSafe(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	return fs.readFileSync(filePath, "utf-8");
+}
+/**
+* Run a shell command synchronously, inheriting stdio.
+*/
+function exec(command, cwd) {
+	execSync(command, {
+		cwd,
+		stdio: "inherit"
+	});
+}
+/**
+* Spawn a process and wait for a specific string in stdout,
+* then resolve with the child process (still running).
+*/
+function spawnAndWaitFor(command, args, cwd, waitFor, timeoutMs = 6e4) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			shell: true
+		});
+		let output = "";
+		const timer = setTimeout(() => {
+			child.kill();
+			reject(/* @__PURE__ */ new Error(`Timed out waiting for "${waitFor}" after ${timeoutMs}ms`));
+		}, timeoutMs);
+		child.stdout?.on("data", (data) => {
+			const text = data.toString();
+			output += text;
+			process.stdout.write(text);
+			if (output.includes(waitFor)) {
+				clearTimeout(timer);
+				resolve(child);
+			}
+		});
+		child.stderr?.on("data", (data) => {
+			process.stderr.write(data.toString());
+		});
+		child.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (!output.includes(waitFor)) reject(/* @__PURE__ */ new Error(`Process exited with code ${code} before "${waitFor}" appeared`));
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/templates.ts
+function docsConfigTemplate(cfg) {
+	return `\
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/fumadocs";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  theme: fumadocs({
+    ui: {
+      colors: { primary: "#6366f1" },
+    },
+  }),
+
+  metadata: {
+    titleTemplate: "%s – ${cfg.projectName}",
+    description: "Documentation for ${cfg.projectName}",
+  },
+});
+`;
+}
+function nextConfigTemplate() {
+	return `\
+import { withDocs } from "@farming-labs/next/config";
+
+export default withDocs();
+`;
+}
+function nextConfigMergedTemplate(existingContent) {
+	if (existingContent.includes("withDocs")) return existingContent;
+	const lines = existingContent.split("\n");
+	const importLine = "import { withDocs } from \"@farming-labs/next/config\";";
+	const exportIdx = lines.findIndex((l) => l.match(/export\s+default/));
+	if (exportIdx === -1) return `${importLine}\n\n${existingContent}\n\nexport default withDocs();\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, "");
+	const adjustedExportIdx = exportIdx + (lastImportIdx >= 0 && exportIdx > lastImportIdx ? 1 : 0);
+	const simpleMatch = lines[adjustedExportIdx].match(/^(\s*export\s+default\s+)(.*?)(;?\s*)$/);
+	if (simpleMatch) {
+		const [, prefix, value, suffix] = simpleMatch;
+		lines[adjustedExportIdx] = `${prefix}withDocs(${value})${suffix}`;
+	}
+	return lines.join("\n");
+}
+function rootLayoutTemplate() {
+	return `\
+import type { Metadata } from "next";
+import { RootProvider } from "@farming-labs/fumadocs";
+import docsConfig from "@/docs.config";
+import "./global.css";
+
+export const metadata: Metadata = {
+  title: {
+    default: "Docs",
+    template: docsConfig.metadata?.titleTemplate ?? "%s",
+  },
+  description: docsConfig.metadata?.description,
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}
+`;
+}
+function globalCssTemplate(theme) {
+	return `\
+@import "tailwindcss";
+@import "@farming-labs/${theme}/css";
+`;
+}
+/**
+* Inject the fumadocs CSS import into an existing global.css.
+* Returns the modified content, or null if already present.
+*/
+function injectCssImport(existingContent, theme) {
+	const importLine = `@import "@farming-labs/${theme}/css";`;
+	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");
+}
+function docsLayoutTemplate() {
+	return `\
+import docsConfig from "@/docs.config";
+import { createDocsLayout } from "@farming-labs/fumadocs";
+
+export default createDocsLayout(docsConfig);
+`;
+}
+function postcssConfigTemplate() {
+	return `\
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
+`;
+}
+function tsconfigTemplate() {
+	return `\
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+`;
+}
+function welcomePageTemplate(cfg) {
+	return `\
+---
+title: "Documentation"
+description: "Welcome to ${cfg.projectName} documentation"
+---
+
+# Welcome to ${cfg.projectName}
+
+Get started with our documentation. Browse the pages on the left to learn more.
+
+<Callout type="info">
+  This documentation was generated by \`@farming-labs/docs\`. Edit the MDX files in \`app/${cfg.entry}/\` to customize.
+</Callout>
+
+## Overview
+
+This is your documentation home page. From here you can navigate to:
+
+- [Installation](/${cfg.entry}/installation) — How to install and set up the project
+- [Quickstart](/${cfg.entry}/quickstart) — Get up and running in minutes
+
+## Features
+
+- **MDX Support** — Write docs with Markdown and React components
+- **Syntax Highlighting** — Code blocks with automatic highlighting
+- **Dark Mode** — Built-in theme switching
+- **Search** — Full-text search across all pages
+- **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 installationPageTemplate(cfg) {
+	return `\
+---
+title: "Installation"
+description: "How to install and set up ${cfg.projectName}"
+---
+
+# Installation
+
+Follow these steps to install and configure ${cfg.projectName}.
+
+<Callout type="info">
+  Prerequisites: Node.js 18+ and a package manager (pnpm, npm, or yarn).
+</Callout>
+
+## Install Dependencies
+
+\`\`\`bash
+pnpm add @farming-labs/docs
+\`\`\`
+
+## Configuration
+
+Your project includes a \`docs.config.ts\` at the root:
+
+\`\`\`ts
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/fumadocs";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  theme: fumadocs({
+    ui: { colors: { primary: "#6366f1" } },
+  }),
+});
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+app/
+  ${cfg.entry}/
+    layout.tsx          # Docs layout
+    page.mdx            # /${cfg.entry}
+    installation/
+      page.mdx          # /${cfg.entry}/installation
+    quickstart/
+      page.mdx          # /${cfg.entry}/quickstart
+docs.config.ts          # Docs configuration
+next.config.ts          # Next.js config with withDocs()
+\`\`\`
+
+## What's Next?
+
+Head to the [Quickstart](/${cfg.entry}/quickstart) guide to start writing your first page.
+`;
+}
+function quickstartPageTemplate(cfg) {
+	return `\
+---
+title: "Quickstart"
+description: "Get up and running in minutes"
+---
+
+# Quickstart
+
+This guide walks you through creating your first documentation page.
+
+## Creating a Page
+
+Create a new folder under \`app/${cfg.entry}/\` with a \`page.mdx\` file:
+
+\`\`\`bash
+mkdir -p app/${cfg.entry}/my-page
+\`\`\`
+
+Then create \`app/${cfg.entry}/my-page/page.mdx\`:
+
+\`\`\`mdx
+---
+title: "My Page"
+description: "A custom documentation page"
+---
+
+# My Page
+
+Write your content here using **Markdown** and JSX components.
+\`\`\`
+
+Your page is now available at \`/${cfg.entry}/my-page\`.
+
+## Using Components
+
+### Callouts
+
+<Callout type="info">
+  This is an informational callout. Use it for tips and notes.
+</Callout>
+
+<Callout type="warn">
+  This is a warning callout. Use it for important caveats.
+</Callout>
+
+### Code Blocks
+
+Code blocks are automatically syntax-highlighted:
+
+\`\`\`typescript
+function greet(name: string): string {
+  return \\\`Hello, \\\${name}!\\\`;
+}
+
+console.log(greet("World"));
+\`\`\`
+
+## Customizing the Theme
+
+Edit \`docs.config.ts\` to change colors, typography, and component defaults:
+
+\`\`\`ts
+theme: fumadocs({
+  ui: {
+    colors: { primary: "#22c55e" },
+  },
+}),
+\`\`\`
+
+## Deploying
+
+Build your docs for production:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
+Deploy to Vercel, Netlify, or any Node.js hosting platform.
+`;
+}
+
+//#endregion
+//#region src/cli/init.ts
+async function init() {
+	const cwd = process.cwd();
+	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
+	if (!detectFramework(cwd)) {
+		p.log.error("Could not detect a supported framework.\n  Make sure you have a " + pc.cyan("package.json") + " with " + pc.cyan("next") + " installed.\n  Supported frameworks: Next.js");
+		p.outro(pc.red("Init cancelled."));
+		process.exit(1);
+	}
+	p.log.success(`Detected framework: ${pc.cyan("Next.js")}`);
+	const theme = await p.select({
+		message: "Which theme would you like to use?",
+		options: [{
+			value: "fumadocs",
+			label: "Fumadocs",
+			hint: "Clean, modern docs theme with sidebar, search, and dark mode"
+		}]
+	});
+	if (p.isCancel(theme)) {
+		p.outro(pc.red("Init cancelled."));
+		process.exit(0);
+	}
+	const entry = await p.text({
+		message: "Where should your docs live?",
+		placeholder: "docs",
+		defaultValue: "docs",
+		validate: (value) => {
+			if (!value) return "Entry path is required";
+			if (value.startsWith("/")) return "Use a relative path (no leading /)";
+			if (value.includes(" ")) return "Path cannot contain spaces";
+		}
+	});
+	if (p.isCancel(entry)) {
+		p.outro(pc.red("Init cancelled."));
+		process.exit(0);
+	}
+	const entryPath = entry;
+	const pkgJson = JSON.parse(readFileSafe(path.join(cwd, "package.json")));
+	const cfg = {
+		entry: entryPath,
+		theme,
+		projectName: pkgJson.name || "My Project"
+	};
+	const s = p.spinner();
+	s.start("Scaffolding docs files");
+	const written = [];
+	const skipped = [];
+	function write(rel, content, overwrite = false) {
+		if (writeFileSafe(path.join(cwd, rel), content, overwrite)) written.push(rel);
+		else skipped.push(rel);
+	}
+	write("docs.config.ts", docsConfigTemplate(cfg));
+	const existingNextConfig = readFileSafe(path.join(cwd, "next.config.ts")) ?? readFileSafe(path.join(cwd, "next.config.mjs")) ?? readFileSafe(path.join(cwd, "next.config.js"));
+	if (existingNextConfig) {
+		const configFile = fileExists(path.join(cwd, "next.config.ts")) ? "next.config.ts" : fileExists(path.join(cwd, "next.config.mjs")) ? "next.config.mjs" : "next.config.js";
+		const merged = nextConfigMergedTemplate(existingNextConfig);
+		if (merged !== existingNextConfig) {
+			writeFileSafe(path.join(cwd, configFile), merged, true);
+			written.push(configFile + " (updated)");
+		} else skipped.push(configFile + " (already configured)");
+	} else write("next.config.ts", nextConfigTemplate());
+	write("app/layout.tsx", rootLayoutTemplate());
+	const globalCssPath = path.join(cwd, "app/global.css");
+	const existingGlobalCss = readFileSafe(globalCssPath);
+	if (existingGlobalCss) {
+		const injected = injectCssImport(existingGlobalCss, theme);
+		if (injected) {
+			writeFileSafe(globalCssPath, injected, true);
+			written.push("app/global.css (updated)");
+		} else skipped.push("app/global.css (already configured)");
+	} else write("app/global.css", globalCssTemplate(theme));
+	write(`app/${entryPath}/layout.tsx`, docsLayoutTemplate());
+	write("postcss.config.mjs", postcssConfigTemplate());
+	if (!fileExists(path.join(cwd, "tsconfig.json"))) write("tsconfig.json", tsconfigTemplate());
+	write(`app/${entryPath}/page.mdx`, welcomePageTemplate(cfg));
+	write(`app/${entryPath}/installation/page.mdx`, installationPageTemplate(cfg));
+	write(`app/${entryPath}/quickstart/page.mdx`, quickstartPageTemplate(cfg));
+	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"));
+	if (skipped.length > 0) p.log.info(`Skipped ${skipped.length} existing file${skipped.length > 1 ? "s" : ""}:\n` + skipped.map((f) => `  ${pc.dim("-")} ${f}`).join("\n"));
+	const pm = detectPackageManager(cwd);
+	p.log.info(`Using ${pc.cyan(pm)} as package manager`);
+	const s2 = p.spinner();
+	s2.start("Installing dependencies");
+	try {
+		exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/next @farming-labs/fumadocs`, cwd);
+		const devDeps = [
+			"@tailwindcss/postcss",
+			"postcss",
+			"tailwindcss",
+			"@types/mdx",
+			"@types/node"
+		];
+		const allDeps = {
+			...pkgJson.dependencies,
+			...pkgJson.devDependencies
+		};
+		const missingDevDeps = devDeps.filter((d) => !allDeps[d]);
+		if (missingDevDeps.length > 0) exec(`${devInstallCommand(pm)} ${missingDevDeps.join(" ")}`, cwd);
+	} catch {
+		s2.stop("Failed to install dependencies");
+		p.log.error(`Dependency installation failed. Run the install command manually:
+  ${pc.cyan(`${installCommand(pm)} @farming-labs/docs`)}`);
+		p.outro(pc.yellow("Setup partially complete. Install deps and run dev server manually."));
+		process.exit(1);
+	}
+	s2.stop("Dependencies installed");
+	const startDev = await p.confirm({
+		message: "Start the dev server now?",
+		initialValue: true
+	});
+	if (p.isCancel(startDev) || !startDev) {
+		p.log.info(`You can start the dev server later with:
+  ${pc.cyan(`${pm === "yarn" ? "yarn" : pm + " run"} dev`)}`);
+		p.outro(pc.green("Done! Happy documenting."));
+		process.exit(0);
+	}
+	p.log.step("Starting dev server...");
+	try {
+		const child = await spawnAndWaitFor("npx", [
+			"next",
+			"dev",
+			"--webpack"
+		], cwd, "Ready", 6e4);
+		const url = `http://localhost:3000/${entryPath}`;
+		console.log();
+		p.log.success(`Dev server is running! Your docs are live at:\n\n  ${pc.cyan(pc.underline(url))}\n\n  Press ${pc.dim("Ctrl+C")} to stop the server.`);
+		p.outro(pc.green("Happy documenting!"));
+		await new Promise((resolve) => {
+			child.on("close", () => resolve());
+			process.on("SIGINT", () => {
+				child.kill("SIGINT");
+				resolve();
+			});
+			process.on("SIGTERM", () => {
+				child.kill("SIGTERM");
+				resolve();
+			});
+		});
+	} catch (err) {
+		p.log.error(`Could not start dev server. Try running manually:
+  ${pc.cyan("npx next dev --webpack")}`);
+		p.outro(pc.yellow("Setup complete. Start the server manually."));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/cli/index.ts
+const command = process.argv.slice(2)[0];
+async function main() {
+	if (!command || command === "init") await init();
+	else if (command === "--help" || command === "-h") printHelp();
+	else if (command === "--version" || command === "-v") printVersion();
+	else {
+		console.error(pc.red(`Unknown command: ${command}`));
+		console.error();
+		printHelp();
+		process.exit(1);
+	}
+}
+function printHelp() {
+	console.log(`
+${pc.bold("@farming-labs/docs")} — Documentation framework CLI
+
+${pc.dim("Usage:")}
+  farming-docs ${pc.cyan("<command>")}
+
+${pc.dim("Commands:")}
+  ${pc.cyan("init")}    Scaffold docs in your project (default)
+
+${pc.dim("Options:")}
+  ${pc.cyan("-h, --help")}       Show this help message
+  ${pc.cyan("-v, --version")}    Show version
+`);
+}
+function printVersion() {
+	console.log("0.1.0");
+}
+main().catch((err) => {
+	console.error(pc.red("An unexpected error occurred:"));
+	console.error(err);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/dist/index.d.mts

@@ -0,0 +1,597 @@
+//#region src/types.d.ts
+/**
+ * Theme / UI configuration types for the docs framework.
+ * Inspired by Fumadocs: https://github.com/fuma-nama/fumadocs
+ */
+/**
+ * Fine-grained UI configuration for docs themes.
+ *
+ * Theme authors define defaults for these values in their `createTheme` call.
+ * End users can override any value when calling the theme factory.
+ *
+ * @example
+ * ```ts
+ * const myTheme = createTheme({
+ *   name: "my-theme",
+ *   ui: {
+ *     colors: { primary: "#6366f1", background: "#0a0a0a" },
+ *     radius: "0px",
+ *     codeBlock: { showLineNumbers: true, theme: "github-dark" },
+ *     sidebar: { width: 280, style: "bordered" },
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Font style configuration for a single text element (heading, body, etc.).
+ *
+ * @example
+ * ```ts
+ * h1: { size: "2.25rem", weight: 700, lineHeight: "1.2", letterSpacing: "-0.02em" }
+ * ```
+ */
+interface FontStyle {
+  /** CSS `font-size` value (e.g. "2.25rem", "36px", "clamp(1.8rem, 3vw, 2.5rem)") */
+  size?: string;
+  /** CSS `font-weight` value (e.g. 700, "bold", "600") */
+  weight?: string | number;
+  /** CSS `line-height` value (e.g. "1.2", "1.5", "28px") */
+  lineHeight?: string;
+  /** CSS `letter-spacing` value (e.g. "-0.02em", "0.05em") */
+  letterSpacing?: string;
+}
+/**
+ * Typography configuration for the docs.
+ *
+ * @example
+ * ```ts
+ * typography: {
+ *   font: {
+ *     style: { sans: "Inter, sans-serif", mono: "JetBrains Mono, monospace" },
+ *     h1: { size: "2.25rem", weight: 700, letterSpacing: "-0.02em" },
+ *     h2: { size: "1.75rem", weight: 600 },
+ *     body: { size: "1rem", lineHeight: "1.75" },
+ *   },
+ * }
+ * ```
+ */
+interface TypographyConfig {
+  /**
+   * Font configuration.
+   */
+  font?: {
+    /**
+     * Font family definitions.
+     */
+    style?: {
+      /** Sans-serif font family — used for body text, headings, and UI elements. */sans?: string; /** Monospace font family — used for code blocks, inline code, and terminal output. */
+      mono?: string;
+    }; /** Heading 1 (`<h1>`) style overrides */
+    h1?: FontStyle; /** Heading 2 (`<h2>`) style overrides */
+    h2?: FontStyle; /** Heading 3 (`<h3>`) style overrides */
+    h3?: FontStyle; /** Heading 4 (`<h4>`) style overrides */
+    h4?: FontStyle; /** Body text style */
+    body?: FontStyle; /** Small text style (captions, meta text) */
+    small?: FontStyle;
+  };
+}
+interface UIConfig {
+  /**
+   * Theme color tokens.
+   *
+   * These are mapped to `--color-fd-*` CSS variables at runtime.
+   * Accepts any valid CSS color value (hex, rgb, oklch, hsl, etc.).
+   *
+   * @example
+   * ```ts
+   * colors: {
+   *   primary: "oklch(0.72 0.19 149)",       // green primary
+   *   primaryForeground: "#ffffff",           // white text on primary
+   *   accent: "hsl(220 80% 60%)",            // blue accent
+   * }
+   * ```
+   */
+  colors?: {
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    mutedForeground?: string;
+    border?: string;
+    card?: string;
+    cardForeground?: string;
+    accent?: string;
+    accentForeground?: string;
+    secondary?: string;
+    secondaryForeground?: string;
+    popover?: string;
+    popoverForeground?: string;
+    ring?: string;
+  };
+  /**
+   * Typography settings — font families, heading sizes, weights, etc.
+   *
+   * @example
+   * ```ts
+   * typography: {
+   *   font: {
+   *     style: { sans: "Inter, sans-serif", mono: "JetBrains Mono, monospace" },
+   *     h1: { size: "2.25rem", weight: 700, letterSpacing: "-0.02em" },
+   *     body: { size: "1rem", lineHeight: "1.75" },
+   *   },
+   * }
+   * ```
+   */
+  typography?: TypographyConfig;
+  /**
+   * Global border-radius. Maps to CSS `--radius`.
+   * Use "0px" for sharp corners, "0.5rem" for rounded, etc.
+   */
+  radius?: string;
+  /** Layout dimensions */
+  layout?: {
+    contentWidth?: number;
+    sidebarWidth?: number;
+    tocWidth?: number;
+    toc?: {
+      enabled?: boolean;
+      depth?: number;
+    };
+    header?: {
+      height?: number;
+      sticky?: boolean;
+    };
+  };
+  /** Code block rendering config */
+  codeBlock?: {
+    /** Show line numbers in code blocks @default false */showLineNumbers?: boolean; /** Show copy button @default true */
+    showCopyButton?: boolean; /** Shiki theme name for syntax highlighting */
+    theme?: string; /** Dark mode shiki theme (for dual-theme setups) */
+    darkTheme?: string;
+  };
+  /** Sidebar styling hints (consumed by theme CSS) */
+  sidebar?: {
+    /**
+     * Visual style of the sidebar.
+     * - "default" — standard fumadocs sidebar
+     * - "bordered" — visible bordered sections (like better-auth)
+     * - "floating" — floating card sidebar
+     */
+    style?: "default" | "bordered" | "floating"; /** Background color override */
+    background?: string; /** Border color override */
+    borderColor?: string;
+  };
+  /** Card styling */
+  card?: {
+    /** Whether cards have visible borders @default true */bordered?: boolean; /** Card background color override */
+    background?: string;
+  };
+  /** Default props/variants for MDX components (Callout, CodeBlock, Tabs, etc.) */
+  components?: {
+    [key: string]: Record<string, unknown> | ((defaults: unknown) => unknown);
+  };
+}
+/**
+ * A docs theme configuration.
+ *
+ * Theme authors create these with `createTheme()`. The `name` identifies the
+ * theme (useful for CSS scoping, debugging, analytics). The `ui` object holds
+ * all visual configuration.
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@farming-labs/docs";
+ *
+ * export const myTheme = createTheme({
+ *   name: "my-theme",
+ *   ui: {
+ *     colors: { primary: "#ff4d8d" },
+ *     radius: "0px",
+ *   },
+ * });
+ * ```
+ */
+interface DocsTheme {
+  /** Unique name for this theme (used for CSS scoping and debugging) */
+  name?: string;
+  /** UI configuration — colors, typography, layout, components */
+  ui?: UIConfig;
+  /**
+   * @internal
+   * User-provided color overrides tracked by `createTheme`.
+   * Only these colors are emitted as inline CSS variables at runtime.
+   * Preset defaults stay in the theme's CSS file.
+   */
+  _userColorOverrides?: Record<string, string>;
+}
+interface DocsMetadata {
+  titleTemplate?: string;
+  description?: string;
+  twitterCard?: "summary" | "summary_large_image";
+}
+interface OGConfig {
+  enabled?: boolean;
+  type?: "static" | "dynamic";
+  endpoint?: string;
+  defaultImage?: string;
+}
+interface PageFrontmatter {
+  title: string;
+  description?: string;
+  tags?: string[];
+  icon?: string;
+  /** Path to custom OG image for this page */
+  ogImage?: string;
+}
+interface DocsNav {
+  /**
+   * Sidebar title — a plain string or a React element (e.g. a div with an icon).
+   *
+   * @example
+   * ```tsx
+   * // Simple string
+   * nav: { title: "My Docs" }
+   *
+   * // React element with icon
+   * nav: {
+   *   title: <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+   *     <Rocket size={18} /> Example Docs
+   *   </div>
+   * }
+   * ```
+   */
+  title?: unknown;
+  /** URL the title links to. Defaults to `/{entry}`. */
+  url?: string;
+}
+interface ThemeToggleConfig {
+  /**
+   * Whether to show the light/dark theme toggle in the sidebar.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * The default / forced theme when the toggle is hidden.
+   * Only applies when `enabled` is `false`.
+   * @default "system"
+   *
+   * @example
+   * ```ts
+   * // Hide toggle, force dark mode
+   * themeToggle: { enabled: false, default: "dark" }
+   * ```
+   */
+  default?: "light" | "dark" | "system";
+  /**
+   * Toggle mode — show only light/dark, or include a system option.
+   * @default "light-dark"
+   */
+  mode?: "light-dark" | "light-dark-system";
+}
+interface BreadcrumbConfig {
+  /**
+   * Whether to show the breadcrumb navigation above page content.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Custom breadcrumb component. Receives the default breadcrumb as children
+   * so you can wrap/modify it.
+   *
+   * @example
+   * ```tsx
+   * breadcrumb: {
+   *   component: ({ items }) => <MyBreadcrumb items={items} />,
+   * }
+   * ```
+   */
+  component?: unknown;
+}
+interface SidebarConfig {
+  /**
+   * Whether to show the sidebar.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Custom sidebar component to completely replace the default sidebar.
+   * Receives the page tree and config as context.
+   *
+   * @example
+   * ```tsx
+   * sidebar: {
+   *   component: MySidebar,
+   * }
+   * ```
+   */
+  component?: unknown;
+  /**
+   * Sidebar footer content (rendered below navigation items).
+   */
+  footer?: unknown;
+  /**
+   * Sidebar banner content (rendered above navigation items).
+   */
+  banner?: unknown;
+  /**
+   * Whether the sidebar is collapsible on desktop.
+   * @default true
+   */
+  collapsible?: boolean;
+}
+/**
+ * A single "Open in …" provider shown in the Open dropdown.
+ *
+ * @example
+ * ```ts
+ * { name: "Claude", icon: <ClaudeIcon />, urlTemplate: "https://claude.ai?url={url}" }
+ * ```
+ */
+interface OpenDocsProvider {
+  /** Display name (e.g. "ChatGPT", "Claude", "Cursor") */
+  name: string;
+  /** Icon element rendered next to the name */
+  icon?: unknown;
+  /**
+   * URL template. `{url}` is replaced with the current page URL.
+   * `{mdxUrl}` is replaced with the `.mdx` variant of the page URL.
+   *
+   * @example "https://claude.ai/new?q=Read+this+doc:+{url}"
+   */
+  urlTemplate: string;
+}
+/**
+ * Configuration for the "Open in …" dropdown that lets users
+ * send the current page to an LLM or external tool.
+ *
+ * @example
+ * ```ts
+ * openDocs: {
+ *   enabled: true,
+ *   providers: [
+ *     { name: "ChatGPT", icon: <ChatGPTIcon />, urlTemplate: "https://chatgpt.com/?q={url}" },
+ *     { name: "Claude", icon: <ClaudeIcon />, urlTemplate: "https://claude.ai/new?q={url}" },
+ *   ],
+ * }
+ * ```
+ */
+interface OpenDocsConfig {
+  /** Whether to show the "Open" dropdown. @default false */
+  enabled?: boolean;
+  /**
+   * List of LLM / tool providers to show in the dropdown.
+   * If not provided, a sensible default list is used.
+   */
+  providers?: OpenDocsProvider[];
+}
+/**
+ * Configuration for the "Copy Markdown" button that copies
+ * the current page's content as Markdown to the clipboard.
+ */
+interface CopyMarkdownConfig {
+  /** Whether to show the "Copy Markdown" button. @default false */
+  enabled?: boolean;
+}
+/**
+ * Page-level action buttons shown above the page content
+ * (e.g. "Copy Markdown", "Open in …" dropdown).
+ *
+ * @example
+ * ```ts
+ * pageActions: {
+ *   copyMarkdown: { enabled: true },
+ *   openDocs: {
+ *     enabled: true,
+ *     providers: [
+ *       { name: "Claude", urlTemplate: "https://claude.ai/new?q={url}" },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+interface PageActionsConfig {
+  /** "Copy Markdown" button */
+  copyMarkdown?: boolean | CopyMarkdownConfig;
+  /** "Open in …" dropdown with LLM / tool providers */
+  openDocs?: boolean | OpenDocsConfig;
+  /**
+   * Where to render the page action buttons relative to the page title.
+   *
+   * - `"below-title"` — render below the first `<h1>` heading (default)
+   * - `"above-title"` — render above the page title / content
+   *
+   * @default "below-title"
+   */
+  position?: "above-title" | "below-title";
+}
+interface DocsConfig {
+  /** Entry folder for docs (e.g. "docs" → /docs) */
+  entry: string;
+  /** Theme configuration - single source of truth for UI */
+  theme?: DocsTheme;
+  /**
+   * Sidebar navigation header.
+   * Customise the title shown at the top of the sidebar.
+   */
+  nav?: DocsNav;
+  /**
+   * Theme toggle (light/dark mode switcher) in the sidebar.
+   *
+   * - `true` or `undefined` → toggle is shown (default)
+   * - `false` → toggle is hidden, defaults to system theme
+   * - `{ enabled: false, default: "dark" }` → toggle hidden, force dark
+   *
+   * @example
+   * ```ts
+   * // Hide toggle, force dark mode
+   * themeToggle: { enabled: false, default: "dark" }
+   *
+   * // Show toggle with system option
+   * themeToggle: { mode: "light-dark-system" }
+   * ```
+   */
+  themeToggle?: boolean | ThemeToggleConfig;
+  /**
+   * Breadcrumb navigation above page content.
+   *
+   * - `true` or `undefined` → breadcrumb is shown (default)
+   * - `false` → breadcrumb is hidden
+   * - `{ enabled: false }` → breadcrumb is hidden
+   * - `{ component: MyBreadcrumb }` → custom breadcrumb component
+   */
+  breadcrumb?: boolean | BreadcrumbConfig;
+  /**
+   * Sidebar customisation.
+   *
+   * - `true` or `undefined` → default sidebar
+   * - `false` → sidebar is hidden
+   * - `{ component: MySidebar }` → custom sidebar component
+   * - `{ footer: <MyFooter />, banner: <MyBanner /> }` → add footer/banner
+   */
+  sidebar?: boolean | SidebarConfig;
+  /**
+   * Custom MDX component overrides.
+   *
+   * Pass your own React components to replace defaults (e.g. Callout, CodeBlock).
+   * Components must match the expected props interface.
+   *
+   * @example
+   * ```ts
+   * import { MyCallout } from "./components/my-callout";
+   *
+   * export default defineDocs({
+   *   entry: "docs",
+   *   theme: fumadocs(),
+   *   components: {
+   *     Callout: MyCallout,
+   *   },
+   * });
+   * ```
+   */
+  components?: Record<string, unknown>;
+  /**
+   * Icon registry for sidebar items.
+   *
+   * Map string labels to React elements. Reference them in page frontmatter
+   * with `icon: "label"` and the matching icon renders in the sidebar.
+   *
+   * @example
+   * ```tsx
+   * import { Book, Terminal, Rocket } from "lucide-react";
+   *
+   * export default defineDocs({
+   *   entry: "docs",
+   *   theme: fumadocs(),
+   *   icons: {
+   *     book: <Book />,
+   *     terminal: <Terminal />,
+   *     rocket: <Rocket />,
+   *   },
+   * });
+   * ```
+   *
+   * Then in `page.mdx` frontmatter:
+   * ```yaml
+   * ---
+   * title: "CLI Reference"
+   * icon: "terminal"
+   * ---
+   * ```
+   */
+  icons?: Record<string, unknown>;
+  /**
+   * Page action buttons shown above the content area.
+   * Includes "Copy Markdown" and "Open in …" (LLM dropdown).
+   *
+   * @example
+   * ```ts
+   * pageActions: {
+   *   copyMarkdown: { enabled: true },
+   *   openDocs: {
+   *     enabled: true,
+   *     providers: [
+   *       { name: "ChatGPT", urlTemplate: "https://chatgpt.com/?q={url}" },
+   *       { name: "Claude", urlTemplate: "https://claude.ai/new?q={url}" },
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  pageActions?: PageActionsConfig;
+  /** SEO metadata - separate from theme */
+  metadata?: DocsMetadata;
+  /** Open Graph image handling */
+  og?: OGConfig;
+}
+//#endregion
+//#region src/define-docs.d.ts
+/**
+ * Define docs configuration. Validates and returns the config.
+ */
+declare function defineDocs(config: DocsConfig): DocsConfig;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Deep merge utility for theme overrides.
+ * Merges objects recursively; later values override earlier ones.
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+//#endregion
+//#region src/create-theme.d.ts
+/**
+ * Create a theme preset factory.
+ *
+ * Returns a function that accepts optional overrides and deep-merges them
+ * with the base theme defaults. This is the same pattern used by the
+ * built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+ *
+ * @param baseTheme - The default theme configuration
+ * @returns A factory function `(overrides?) => DocsTheme`
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@farming-labs/docs";
+ *
+ * export const myTheme = createTheme({
+ *   name: "my-theme",
+ *   ui: {
+ *     colors: { primary: "#6366f1" },
+ *     layout: { contentWidth: 800 },
+ *   },
+ * });
+ * ```
+ */
+declare function createTheme(baseTheme: DocsTheme): (overrides?: Partial<DocsTheme>) => DocsTheme;
+/**
+ * Extend an existing theme preset with additional defaults.
+ *
+ * Useful when you want to build on top of an existing theme (e.g. fumadocs)
+ * rather than starting from scratch.
+ *
+ * @example
+ * ```ts
+ * import { extendTheme } from "@farming-labs/docs";
+ * import { fumadocs } from "@farming-labs/fumadocs/default";
+ *
+ * // Start with fumadocs defaults, override some values
+ * export const myTheme = extendTheme(fumadocs(), {
+ *   name: "my-custom-fumadocs",
+ *   ui: { colors: { primary: "#22c55e" } },
+ * });
+ * ```
+ */
+declare function extendTheme(baseTheme: DocsTheme, extensions: Partial<DocsTheme>): DocsTheme;
+//#endregion
+//#region src/metadata.d.ts
+/**
+ * Resolve page title using metadata titleTemplate.
+ * %s is replaced with page title.
+ */
+declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): string;
+/**
+ * Resolve OG image URL for a page.
+ */
+declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
+//#endregion
+export { type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type PageActionsConfig, type PageFrontmatter, type SidebarConfig, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -0,0 +1,116 @@
+//#region src/define-docs.ts
+/**
+* Define docs configuration. Validates and returns the config.
+*/
+function defineDocs(config) {
+	return {
+		entry: config.entry ?? "docs",
+		theme: config.theme,
+		nav: config.nav,
+		themeToggle: config.themeToggle,
+		breadcrumb: config.breadcrumb,
+		sidebar: config.sidebar,
+		components: config.components,
+		icons: config.icons,
+		pageActions: config.pageActions,
+		metadata: config.metadata,
+		og: config.og
+	};
+}
+
+//#endregion
+//#region src/utils.ts
+/**
+* Deep merge utility for theme overrides.
+* Merges objects recursively; later values override earlier ones.
+*/
+function deepMerge(target, ...sources) {
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return target;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sourceVal = source[key];
+		const targetVal = result[key];
+		if (sourceVal && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal && typeof targetVal === "object" && !Array.isArray(targetVal)) result[key] = deepMerge(targetVal, sourceVal);
+		else if (sourceVal !== void 0) result[key] = sourceVal;
+	}
+	if (sources.length) return deepMerge(result, ...sources);
+	return result;
+}
+
+//#endregion
+//#region src/create-theme.ts
+/**
+* Create a theme preset factory.
+*
+* Returns a function that accepts optional overrides and deep-merges them
+* with the base theme defaults. This is the same pattern used by the
+* built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+*
+* @param baseTheme - The default theme configuration
+* @returns A factory function `(overrides?) => DocsTheme`
+*
+* @example
+* ```ts
+* import { createTheme } from "@farming-labs/docs";
+*
+* export const myTheme = createTheme({
+*   name: "my-theme",
+*   ui: {
+*     colors: { primary: "#6366f1" },
+*     layout: { contentWidth: 800 },
+*   },
+* });
+* ```
+*/
+function createTheme(baseTheme) {
+	return function themeFactory(overrides = {}) {
+		const merged = deepMerge(baseTheme, overrides);
+		if (overrides.ui?.colors) merged._userColorOverrides = { ...overrides.ui.colors };
+		return merged;
+	};
+}
+/**
+* Extend an existing theme preset with additional defaults.
+*
+* Useful when you want to build on top of an existing theme (e.g. fumadocs)
+* rather than starting from scratch.
+*
+* @example
+* ```ts
+* import { extendTheme } from "@farming-labs/docs";
+* import { fumadocs } from "@farming-labs/fumadocs/default";
+*
+* // Start with fumadocs defaults, override some values
+* export const myTheme = extendTheme(fumadocs(), {
+*   name: "my-custom-fumadocs",
+*   ui: { colors: { primary: "#22c55e" } },
+* });
+* ```
+*/
+function extendTheme(baseTheme, extensions) {
+	return deepMerge(baseTheme, extensions);
+}
+
+//#endregion
+//#region src/metadata.ts
+/**
+* Resolve page title using metadata titleTemplate.
+* %s is replaced with page title.
+*/
+function resolveTitle(pageTitle, metadata) {
+	return (metadata?.titleTemplate ?? "%s").replace("%s", pageTitle);
+}
+/**
+* Resolve OG image URL for a page.
+*/
+function resolveOGImage(page, ogConfig, baseUrl) {
+	if (!ogConfig?.enabled) return void 0;
+	if (page.ogImage) return page.ogImage.startsWith("/") || page.ogImage.startsWith("http") ? page.ogImage : `${baseUrl ?? ""}${page.ogImage}`;
+	if (ogConfig.type === "dynamic" && ogConfig.endpoint) return `${baseUrl ?? ""}${ogConfig.endpoint}`;
+	return ogConfig.defaultImage;
+}
+
+//#endregion
+export { createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@farming-labs/docs",
+  "version": "0.0.2-beta.1",
+  "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "bin": {
+    "farming-docs": "./dist/cli/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "docs",
+    "mdx",
+    "documentation"
+  ],
+  "author": "Farming Labs",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "gray-matter": "^4.0.3",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}