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

package/dist/cli/index.mjs

@@ -16,6 +16,7 @@ function detectFramework(cwd) {
 	};
 	if (allDeps["next"]) return "nextjs";
 	if (allDeps["@sveltejs/kit"]) return "sveltekit";
+	if (allDeps["astro"]) return "astro";
 	return null;
 }
 function detectPackageManager(cwd) {
@@ -133,22 +134,28 @@ const THEME_INFO = {
 		factory: "fumadocs",
 		nextImport: "@farming-labs/theme",
 		svelteImport: "@farming-labs/svelte-theme",
+		astroImport: "@farming-labs/astro-theme",
 		nextCssImport: "default",
-		svelteCssTheme: "fumadocs"
+		svelteCssTheme: "fumadocs",
+		astroCssTheme: "fumadocs"
 	},
 	darksharp: {
 		factory: "darksharp",
 		nextImport: "@farming-labs/theme/darksharp",
 		svelteImport: "@farming-labs/svelte-theme/darksharp",
+		astroImport: "@farming-labs/astro-theme/darksharp",
 		nextCssImport: "darksharp",
-		svelteCssTheme: "darksharp"
+		svelteCssTheme: "darksharp",
+		astroCssTheme: "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",
 		nextCssImport: "pixel-border",
-		svelteCssTheme: "pixel-border"
+		svelteCssTheme: "pixel-border",
+		astroCssTheme: "pixel-border"
 	}
 };
 function getThemeInfo(theme) {
@@ -178,6 +185,17 @@ function sveltePageConfigImport(useAlias) {
 function svelteLayoutServerImport(useAlias) {
 	return useAlias ? "$lib/docs.server" : "../../lib/docs.server";
 }
+function astroServerConfigImport(useAlias) {
+	return useAlias ? "@/lib/docs.config" : "./docs.config";
+}
+function astroPageConfigImport(useAlias, depth) {
+	if (useAlias) return "@/lib/docs.config";
+	return `${"../".repeat(depth)}lib/docs.config`;
+}
+function astroPageServerImport(useAlias, depth) {
+	if (useAlias) return "@/lib/docs.server";
+	return `${"../".repeat(depth)}lib/docs.server`;
+}
 function docsConfigTemplate(cfg) {
 	const t = getThemeInfo(cfg.theme);
 	return `\
@@ -765,6 +783,327 @@ Build your docs for production:
 pnpm build
 \`\`\`
 
+Deploy to Vercel, Netlify, or any Node.js hosting platform.
+`;
+}
+function astroDocsConfigTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	return `\
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.astroImport}";
+
+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 astroDocsServerTemplate(cfg) {
+	return `\
+import { createDocsServer } from "@farming-labs/astro/server";
+import config from "${astroServerConfigImport(cfg.useAlias)}";
+
+const contentFiles = import.meta.glob("/${cfg.entry ?? "docs"}/**/*.{md,mdx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+export const { load, GET, POST } = createDocsServer({
+  ...config,
+  _preloadedContent: contentFiles,
+});
+`;
+}
+const ASTRO_ADAPTER_INFO = {
+	vercel: {
+		pkg: "@astrojs/vercel",
+		import: "@astrojs/vercel"
+	},
+	netlify: {
+		pkg: "@astrojs/netlify",
+		import: "@astrojs/netlify"
+	},
+	node: {
+		pkg: "@astrojs/node",
+		import: "@astrojs/node"
+	},
+	cloudflare: {
+		pkg: "@astrojs/cloudflare",
+		import: "@astrojs/cloudflare"
+	}
+};
+function getAstroAdapterPkg(adapter) {
+	return ASTRO_ADAPTER_INFO[adapter]?.pkg ?? ASTRO_ADAPTER_INFO.vercel.pkg;
+}
+function astroConfigTemplate(adapter = "vercel") {
+	const info = ASTRO_ADAPTER_INFO[adapter] ?? ASTRO_ADAPTER_INFO.vercel;
+	const adapterCall = adapter === "node" ? `${adapter}({ mode: "standalone" })` : `${adapter}()`;
+	return `\
+import { defineConfig } from "astro/config";
+import ${adapter} from "${info.import}";
+
+export default defineConfig({
+  output: "server",
+  adapter: ${adapterCall},
+});
+`;
+}
+function astroDocsPageTemplate(cfg) {
+	return `\
+---
+import DocsLayout from "@farming-labs/astro-theme/src/components/DocsLayout.astro";
+import DocsContent from "@farming-labs/astro-theme/src/components/DocsContent.astro";
+import SearchDialog from "@farming-labs/astro-theme/src/components/SearchDialog.astro";
+import config from "${astroPageConfigImport(cfg.useAlias, 2)}";
+import { load } from "${astroPageServerImport(cfg.useAlias, 2)}";
+import "${`@farming-labs/astro-theme/${getThemeInfo(cfg.theme).astroCssTheme}/css`}";
+
+const data = await load(Astro.url.pathname);
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{data.title} – Docs</title>
+  </head>
+  <body>
+    <DocsLayout tree={data.tree} config={config}>
+      <DocsContent data={data} config={config} />
+    </DocsLayout>
+    <SearchDialog config={config} />
+  </body>
+</html>
+`;
+}
+function astroDocsIndexTemplate(cfg) {
+	return `\
+---
+import DocsLayout from "@farming-labs/astro-theme/src/components/DocsLayout.astro";
+import DocsContent from "@farming-labs/astro-theme/src/components/DocsContent.astro";
+import SearchDialog from "@farming-labs/astro-theme/src/components/SearchDialog.astro";
+import config from "${astroPageConfigImport(cfg.useAlias, 2)}";
+import { load } from "${astroPageServerImport(cfg.useAlias, 2)}";
+import "${`@farming-labs/astro-theme/${getThemeInfo(cfg.theme).astroCssTheme}/css`}";
+
+const data = await load(Astro.url.pathname);
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{data.title} – Docs</title>
+  </head>
+  <body>
+    <DocsLayout tree={data.tree} config={config}>
+      <DocsContent data={data} config={config} />
+    </DocsLayout>
+    <SearchDialog config={config} />
+  </body>
+</html>
+`;
+}
+function astroApiRouteTemplate(cfg) {
+	return `\
+import type { APIRoute } from "astro";
+import { GET as docsGET, POST as docsPOST } from "${astroPageServerImport(cfg.useAlias, 2)}";
+
+export const GET: APIRoute = async ({ request }) => {
+  return docsGET({ request });
+};
+
+export const POST: APIRoute = async ({ request }) => {
+  return docsPOST({ request });
+};
+`;
+}
+function astroGlobalCssTemplate(theme) {
+	return `\
+@import "@farming-labs/astro-theme/${theme}/css";
+`;
+}
+function astroCssImportLine(theme) {
+	return `@import "@farming-labs/astro-theme/${theme}/css";`;
+}
+function injectAstroCssImport(existingContent, theme) {
+	const importLine = astroCssImportLine(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");
+}
+function astroWelcomePageTemplate(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.
+
+## 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
+- **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 astroInstallationPageTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	return `\
+---
+title: "Installation"
+description: "How to install and set up ${cfg.projectName}"
+---
+
+# 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/astro @farming-labs/astro-theme
+\\\`\\\`\\\`
+
+## Configuration
+
+Your project includes a \\\`docs.config.ts\\\` in \\\`src/lib/\\\`:
+
+\\\`\\\`\\\`ts title="src/lib/docs.config.ts"
+import { defineDocs } from "@farming-labs/docs";
+import { ${t.factory} } from "${t.astroImport}";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: ${t.factory}({
+    ui: { colors: { primary: "#6366f1" } },
+  }),
+});
+\\\`\\\`\\\`
+
+## Project Structure
+
+\\\`\\\`\\\`
+${cfg.entry}/                   # Markdown content
+  page.md                      # /${cfg.entry}
+  installation/
+    page.md                    # /${cfg.entry}/installation
+  quickstart/
+    page.md                    # /${cfg.entry}/quickstart
+src/
+  lib/
+    docs.config.ts             # Docs configuration
+    docs.server.ts             # Server-side docs loader
+  pages/
+    ${cfg.entry}/
+      index.astro              # Docs index page
+      [...slug].astro          # Dynamic doc page
+    api/
+      ${cfg.entry}.ts          # Search/AI API route
+\\\`\\\`\\\`
+
+## What's Next?
+
+Head to the [Quickstart](/${cfg.entry}/quickstart) guide to start writing your first page.
+`;
+}
+function astroQuickstartPageTemplate(cfg) {
+	const t = getThemeInfo(cfg.theme);
+	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 \\\`${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 \\\`src/lib/docs.config.ts\\\` to change colors, typography, and component defaults:
+
+\\\`\\\`\\\`ts title="src/lib/docs.config.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.
 `;
 }
@@ -776,21 +1115,29 @@ async function init() {
 	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
 	let framework = detectFramework(cwd);
 	if (framework) {
-		const frameworkName = framework === "nextjs" ? "Next.js" : "SvelteKit";
+		const frameworkName = framework === "nextjs" ? "Next.js" : framework === "sveltekit" ? "SvelteKit" : "Astro";
 		p.log.success(`Detected framework: ${pc.cyan(frameworkName)}`);
 	} else {
 		p.log.warn("Could not auto-detect a framework from " + pc.cyan("package.json") + ".");
 		const picked = await p.select({
 			message: "Which framework are you using?",
-			options: [{
-				value: "nextjs",
-				label: "Next.js",
-				hint: "React framework with App Router"
-			}, {
-				value: "sveltekit",
-				label: "SvelteKit",
-				hint: "Svelte framework with file-based routing"
-			}]
+			options: [
+				{
+					value: "nextjs",
+					label: "Next.js",
+					hint: "React framework with App Router"
+				},
+				{
+					value: "sveltekit",
+					label: "SvelteKit",
+					hint: "Svelte framework with file-based routing"
+				},
+				{
+					value: "astro",
+					label: "Astro",
+					hint: "Content-focused framework with island architecture"
+				}
+			]
 		});
 		if (p.isCancel(picked)) {
 			p.outro(pc.red("Init cancelled."));
@@ -822,7 +1169,7 @@ async function init() {
 		p.outro(pc.red("Init cancelled."));
 		process.exit(0);
 	}
-	const aliasHint = framework === "nextjs" ? `Uses ${pc.cyan("@/")} prefix (requires tsconfig paths)` : `Uses ${pc.cyan("$lib/")} prefix (SvelteKit built-in)`;
+	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 useAlias = await p.confirm({
 		message: `Use path aliases for imports? ${pc.dim(aliasHint)}`,
 		initialValue: false
@@ -831,6 +1178,37 @@ async function init() {
 		p.outro(pc.red("Init cancelled."));
 		process.exit(0);
 	}
+	let astroAdapter;
+	if (framework === "astro") {
+		const adapter = await p.select({
+			message: "Where will you deploy?",
+			options: [
+				{
+					value: "vercel",
+					label: "Vercel",
+					hint: "Recommended for most projects"
+				},
+				{
+					value: "netlify",
+					label: "Netlify"
+				},
+				{
+					value: "cloudflare",
+					label: "Cloudflare Pages"
+				},
+				{
+					value: "node",
+					label: "Node.js / Docker",
+					hint: "Self-hosted standalone server"
+				}
+			]
+		});
+		if (p.isCancel(adapter)) {
+			p.outro(pc.red("Init cancelled."));
+			process.exit(0);
+		}
+		astroAdapter = adapter;
+	}
 	const entry = await p.text({
 		message: "Where should your docs live?",
 		placeholder: "docs",
@@ -848,7 +1226,7 @@ async function init() {
 	const entryPath = entry;
 	const detectedCssFiles = detectGlobalCssFiles(cwd);
 	let globalCssRelPath;
-	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : "app/globals.css";
+	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : framework === "astro" ? "src/styles/global.css" : "app/globals.css";
 	if (detectedCssFiles.length === 1) {
 		globalCssRelPath = detectedCssFiles[0];
 		p.log.info(`Found global CSS at ${pc.cyan(globalCssRelPath)}`);
@@ -888,7 +1266,8 @@ async function init() {
 		theme,
 		projectName: pkgJson.name || "My Project",
 		framework,
-		useAlias
+		useAlias,
+		astroAdapter
 	};
 	const s = p.spinner();
 	s.start("Scaffolding docs files");
@@ -899,6 +1278,7 @@ async function init() {
 		else skipped.push(rel);
 	}
 	if (framework === "sveltekit") scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written);
+	else if (framework === "astro") scaffoldAstro(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"));
@@ -909,7 +1289,10 @@ async function init() {
 	s2.start("Installing dependencies");
 	try {
 		if (framework === "sveltekit") exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme`, cwd);
-		else {
+		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 {
 			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/next @farming-labs/theme`, cwd);
 			const devDeps = [
 				"@tailwindcss/postcss",
@@ -948,6 +1331,10 @@ async function init() {
 		cmd: "npx",
 		args: ["vite", "dev"],
 		waitFor: "ready"
+	} : framework === "astro" ? {
+		cmd: "npx",
+		args: ["astro", "dev"],
+		waitFor: "ready"
 	} : {
 		cmd: "npx",
 		args: [
@@ -957,7 +1344,7 @@ async function init() {
 		],
 		waitFor: "Ready"
 	};
-	const defaultPort = framework === "sveltekit" ? "5173" : "3000";
+	const defaultPort = framework === "sveltekit" ? "5173" : framework === "astro" ? "4321" : "3000";
 	try {
 		const child = await spawnAndWaitFor(devCommand.cmd, devCommand.args, cwd, devCommand.waitFor, 6e4);
 		const url = `http://localhost:${defaultPort}/${entryPath}`;
@@ -976,7 +1363,7 @@ async function init() {
 			});
 		});
 	} catch (err) {
-		const manualCmd = framework === "sveltekit" ? "npx vite dev" : "npx next dev --webpack";
+		const manualCmd = framework === "sveltekit" ? "npx vite dev" : framework === "astro" ? "npx astro 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."));
@@ -1037,6 +1424,32 @@ function scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written)
 	write(`${cfg.entry}/installation/page.md`, svelteInstallationPageTemplate(cfg));
 	write(`${cfg.entry}/quickstart/page.md`, svelteQuickstartPageTemplate(cfg));
 }
+function scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written) {
+	write("src/lib/docs.config.ts", astroDocsConfigTemplate(cfg));
+	write("src/lib/docs.server.ts", astroDocsServerTemplate(cfg));
+	if (!fileExists(path.join(cwd, "astro.config.mjs")) && !fileExists(path.join(cwd, "astro.config.ts"))) write("astro.config.mjs", astroConfigTemplate(cfg.astroAdapter ?? "vercel"));
+	write(`src/pages/${cfg.entry}/index.astro`, astroDocsIndexTemplate(cfg));
+	write(`src/pages/${cfg.entry}/[...slug].astro`, astroDocsPageTemplate(cfg));
+	write(`src/pages/api/${cfg.entry}.ts`, astroApiRouteTemplate(cfg));
+	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
+	const existingGlobalCss = readFileSafe(globalCssAbsPath);
+	const cssTheme = {
+		fumadocs: "fumadocs",
+		darksharp: "darksharp",
+		"pixel-border": "pixel-border",
+		default: "fumadocs"
+	}[cfg.theme] || "fumadocs";
+	if (existingGlobalCss) {
+		const injected = injectAstroCssImport(existingGlobalCss, cssTheme);
+		if (injected) {
+			writeFileSafe(globalCssAbsPath, injected, true);
+			written.push(globalCssRelPath + " (updated)");
+		} else skipped.push(globalCssRelPath + " (already configured)");
+	} else write(globalCssRelPath, astroGlobalCssTemplate(cssTheme));
+	write(`${cfg.entry}/page.md`, astroWelcomePageTemplate(cfg));
+	write(`${cfg.entry}/installation/page.md`, astroInstallationPageTemplate(cfg));
+	write(`${cfg.entry}/quickstart/page.md`, astroQuickstartPageTemplate(cfg));
+}
 
 //#endregion
 //#region src/cli/index.ts
@@ -1063,7 +1476,7 @@ ${pc.dim("Commands:")}
   ${pc.cyan("init")}    Scaffold docs in your project (default)
 
 ${pc.dim("Supported frameworks:")}
-  Next.js, SvelteKit
+  Next.js, SvelteKit, Astro
 
 ${pc.dim("Options:")}
   ${pc.cyan("-h, --help")}       Show this help message

package/package.json

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