@farming-labs/docs 0.0.2-beta.13 → 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 `\
@@ -527,6 +545,7 @@ function svelteDocsServerTemplate(cfg) {
 import { createDocsServer } from "@farming-labs/svelte/server";
 import config from "${svelteServerConfigImport(cfg.useAlias)}";
 
+// preload for production
 const contentFiles = import.meta.glob("/${cfg.entry ?? "docs"}/**/*.{md,mdx,svx}", {
   query: "?raw",
   import: "default",
@@ -764,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.
 `;
 }
@@ -775,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."));
@@ -821,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
@@ -830,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",
@@ -847,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)}`);
@@ -887,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");
@@ -898,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"));
@@ -908,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",
@@ -947,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: [
@@ -956,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}`;
@@ -975,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."));
@@ -1036,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
@@ -1062,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/dist/index.d.mts

@@ -223,6 +223,8 @@ interface PageFrontmatter {
   icon?: string;
   /** Path to custom OG image for this page */
   ogImage?: string;
+  /** Sort order in the sidebar. Lower numbers appear first. Pages without `order` are sorted alphabetically after ordered pages. */
+  order?: number;
 }
 interface DocsNav {
   /**
@@ -677,6 +679,30 @@ interface AIConfig {
     name: string;
   }) => unknown;
 }
+/**
+ * A single item in the slug-based sidebar ordering.
+ *
+ * @example
+ * ```ts
+ * ordering: [
+ *   { slug: "installation" },
+ *   { slug: "cli" },
+ *   { slug: "themes", children: [
+ *     { slug: "default" },
+ *     { slug: "darksharp" },
+ *     { slug: "pixel-border" },
+ *     { slug: "creating-themes" },
+ *   ]},
+ *   { slug: "reference" },
+ * ]
+ * ```
+ */
+interface OrderingItem {
+  /** Folder name (not the full path, just the directory name at this level) */
+  slug: string;
+  /** Ordering for child pages within this folder */
+  children?: OrderingItem[];
+}
 interface DocsConfig {
   /** Entry folder for docs (e.g. "docs" → /docs) */
   entry: string;
@@ -849,6 +875,40 @@ interface DocsConfig {
    * ```
    */
   ai?: AIConfig;
+  /**
+   * Sidebar ordering strategy.
+   *
+   * - `"alphabetical"` — sort pages alphabetically by folder name (default)
+   * - `"numeric"` — sort by frontmatter `order` field (lower first, unset pages last)
+   * - `OrderingItem[]` — explicit slug-based ordering with nested children
+   *
+   * @default "alphabetical"
+   *
+   * @example
+   * ```ts
+   * // Alphabetical (default)
+   * ordering: "alphabetical",
+   *
+   * // Use frontmatter `order: 1`, `order: 2`, etc.
+   * ordering: "numeric",
+   *
+   * // Explicit slug-based ordering
+   * ordering: [
+   *   { slug: "installation" },
+   *   { slug: "cli" },
+   *   { slug: "configuration" },
+   *   { slug: "themes", children: [
+   *     { slug: "default" },
+   *     { slug: "darksharp" },
+   *     { slug: "pixel-border" },
+   *     { slug: "creating-themes" },
+   *   ]},
+   *   { slug: "customization" },
+   *   { slug: "reference" },
+   * ]
+   * ```
+   */
+  ordering?: "alphabetical" | "numeric" | OrderingItem[];
   /** SEO metadata - separate from theme */
   metadata?: DocsMetadata;
   /** Open Graph image handling */
@@ -924,4 +984,4 @@ declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): strin
  */
 declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
 //#endregion
-export { type AIConfig, type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type PageActionsConfig, type PageFrontmatter, type SidebarConfig, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };
+export { type AIConfig, type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type SidebarConfig, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -16,6 +16,7 @@ function defineDocs(config) {
 		icons: config.icons,
 		pageActions: config.pageActions,
 		ai: config.ai,
+		ordering: config.ordering,
 		metadata: config.metadata,
 		og: config.og
 	};

package/package.json

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