@farming-labs/docs 0.0.2-beta.2 → 0.0.2-beta.20

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;
@@ -223,6 +230,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 {
   /**
@@ -319,6 +328,17 @@ interface SidebarConfig {
    * @default true
    */
   collapsible?: boolean;
+  /**
+   * When true, all folder children are rendered flat in the sidebar
+   * (no collapsible sections). Folder index pages appear as category
+   * headings with all children listed directly below them.
+   *
+   * This creates a Mintlify-style sidebar where all navigation items
+   * are always visible.
+   *
+   * @default false
+   */
+  flat?: boolean;
 }
 /**
  * A single "Open in …" provider shown in the Open dropdown.
@@ -404,6 +424,39 @@ interface PageActionsConfig {
    * @default "below-title"
    */
   position?: "above-title" | "below-title";
+  /**
+   * Horizontal alignment of page action buttons.
+   *
+   * - `"left"` — align to the left (default)
+   * - `"right"` — align to the right
+   *
+   * @default "left"
+   */
+  alignment?: "left" | "right";
+}
+/**
+ * Configuration for the "Last updated" date display.
+ *
+ * @example
+ * ```ts
+ * lastUpdated: { position: "below-title" }
+ * ```
+ */
+interface LastUpdatedConfig {
+  /**
+   * Whether to show the "Last updated" date.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Where to render the "Last updated" date.
+   *
+   * - `"footer"` — next to the "Edit on GitHub" link at the bottom (default)
+   * - `"below-title"` — below the page title/description, above the content
+   *
+   * @default "footer"
+   */
+  position?: "footer" | "below-title";
 }
 /**
  * GitHub repository configuration for "Edit on GitHub" links
@@ -442,9 +495,295 @@ interface GithubConfig {
    */
   directory?: string;
 }
+/**
+ * Configuration for "Ask AI" — a RAG-powered chat that lets users
+ * ask questions about the documentation content.
+ *
+ * The AI handler searches relevant doc pages, builds context, and
+ * streams a response from an LLM (OpenAI-compatible API).
+ *
+ * The API key is **never** stored in the config. It is read from the
+ * `OPENAI_API_KEY` environment variable at runtime on the server.
+ *
+ * @example
+ * ```ts
+ * ai: {
+ *   enabled: true,
+ *   model: "gpt-4o-mini",
+ *   systemPrompt: "You are a helpful assistant for our developer docs.",
+ * }
+ * ```
+ */
+interface AIConfig {
+  /**
+   * Whether to enable "Ask AI" functionality.
+   * When enabled, the unified `/api/docs` route handler will accept
+   * POST requests for AI chat.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * How the AI chat UI is presented.
+   *
+   * - `"search"` — AI tab integrated into the Cmd+K search dialog (default)
+   * - `"floating"` — A floating chat widget (bubble button + slide-out panel)
+   *
+   * @default "search"
+   *
+   * @example
+   * ```ts
+   * // Floating chat bubble in the bottom-right corner
+   * ai: {
+   *   enabled: true,
+   *   mode: "floating",
+   *   position: "bottom-right",
+   * }
+   * ```
+   */
+  mode?: "search" | "floating" | "sidebar-icon";
+  /**
+   * Position of the floating chat button on screen.
+   * Only used when `mode` is `"floating"`.
+   *
+   * - `"bottom-right"` — bottom-right corner (default)
+   * - `"bottom-left"` — bottom-left corner
+   * - `"bottom-center"` — bottom center
+   *
+   * @default "bottom-right"
+   */
+  position?: "bottom-right" | "bottom-left" | "bottom-center";
+  /**
+   * Visual style of the floating chat when opened.
+   * Only used when `mode` is `"floating"`.
+   *
+   * - `"panel"` — A tall panel that slides up from the button position (default).
+   *   Stays anchored near the floating button. No backdrop overlay.
+   *
+   * - `"modal"` — A centered modal dialog with a backdrop overlay,
+   *   similar to the Cmd+K search dialog. Feels more focused and immersive.
+   *
+   * - `"popover"` — A compact popover near the button. Smaller than the
+   *   panel, suitable for quick questions without taking much screen space.
+   *
+   * - `"full-modal"` — A full-screen immersive overlay (inspired by better-auth).
+   *   Messages scroll in the center, input is pinned at the bottom.
+   *   Suggested questions appear as horizontal pills. Best for
+   *   documentation-heavy sites that want a premium AI experience.
+   *
+   * @default "panel"
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   mode: "floating",
+   *   position: "bottom-right",
+   *   floatingStyle: "full-modal",
+   * }
+   * ```
+   */
+  floatingStyle?: "panel" | "modal" | "popover" | "full-modal";
+  /**
+   * Custom trigger component for the floating chat button (Next.js only).
+   * Only used when `mode` is `"floating"`.
+   *
+   * 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
+   * // 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;
+  /**
+   * The LLM model to use for chat completions.
+   * Must be compatible with the OpenAI Chat Completions API.
+   * @default "gpt-4o-mini"
+   */
+  model?: string;
+  /**
+   * Custom system prompt prepended to the AI conversation.
+   * The documentation context is automatically appended after this prompt.
+   *
+   * @default "You are a helpful documentation assistant. Answer questions
+   * based on the provided documentation context. Be concise and accurate.
+   * If the answer is not in the context, say so honestly."
+   */
+  systemPrompt?: string;
+  /**
+   * Base URL for an OpenAI-compatible API endpoint.
+   * Use this to point to a self-hosted model, Azure OpenAI, or any
+   * compatible provider (e.g. Groq, Together, OpenRouter).
+   * @default "https://api.openai.com/v1"
+   */
+  baseUrl?: string;
+  /**
+   * API key for the LLM provider.
+   * Pass it via an environment variable to keep it out of source control.
+   *
+   * @default process.env.OPENAI_API_KEY
+   *
+   * @example
+   * ```ts
+   * // Default — reads OPENAI_API_KEY automatically
+   * ai: { enabled: true }
+   *
+   * // Custom provider key
+   * ai: {
+   *   enabled: true,
+   *   apiKey: process.env.GROQ_API_KEY,
+   * }
+   * ```
+   */
+  apiKey?: string;
+  /**
+   * Maximum number of search results to include as context for the AI.
+   * More results = more context but higher token usage.
+   * @default 5
+   */
+  maxResults?: number;
+  /**
+   * Pre-filled suggested questions shown in the AI chat when empty.
+   * When a user clicks one, it fills the input and submits automatically.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   suggestedQuestions: [
+   *     "How do I install this?",
+   *     "What themes are available?",
+   *     "How do I create a custom component?",
+   *   ],
+   * }
+   * ```
+   */
+  suggestedQuestions?: string[];
+  /**
+   * Display name for the AI assistant in the chat UI.
+   * Shown as the message label, header title, and passed to the loading component.
+   *
+   * @default "AI"
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   aiLabel: "DocsBot",
+   * }
+   * ```
+   */
+  aiLabel?: string;
+  /**
+   * The npm package name used in import examples.
+   * The AI will use this in code snippets instead of generic placeholders.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   packageName: "@farming-labs/docs",
+   * }
+   * ```
+   */
+  packageName?: string;
+  /**
+   * The public URL of the documentation site.
+   * The AI will use this for links instead of relative paths.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   docsUrl: "https://docs.farming-labs.dev",
+   * }
+   * ```
+   */
+  docsUrl?: string;
+  /**
+   * Custom loading indicator shown while the AI is generating a response.
+   * Replaces the default "AI is thinking..." indicator.
+   *
+   * Pass a function that receives `{ name }` (the `aiLabel` value) and
+   * returns a React element. This way you don't need to duplicate the label.
+   *
+   * @example
+   * ```tsx
+   * ai: {
+   *   enabled: true,
+   *   aiLabel: "Sage",
+   *   loadingComponent: ({ name }) => (
+   *     <div className="flex items-center gap-2 text-sm text-zinc-400">
+   *       <span className="animate-pulse">🤔</span>
+   *       <span>{name} is thinking...</span>
+   *     </div>
+   *   ),
+   * }
+   * ```
+   */
+  loadingComponent?: (props: {
+    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;
+  /** Path to the content directory. Defaults to `entry` value. */
+  contentDir?: string;
   /** Theme configuration - single source of truth for UI */
   theme?: DocsTheme;
   /**
@@ -579,6 +918,91 @@ interface DocsConfig {
    * ```
    */
   pageActions?: PageActionsConfig;
+  /**
+   * Configuration for the "Last updated" date display.
+   *
+   * - `true` or `undefined` → shown in footer next to "Edit on GitHub" (default)
+   * - `false` → hidden
+   * - `{ position: "below-title" }` → shown below the page title
+   * - `{ position: "footer" }` → shown next to "Edit on GitHub" (default)
+   *
+   * @example
+   * ```ts
+   * // Show below title (Mintlify style)
+   * lastUpdated: { position: "below-title" }
+   *
+   * // Hide entirely
+   * lastUpdated: false
+   * ```
+   */
+  lastUpdated?: boolean | LastUpdatedConfig;
+  /**
+   * AI-powered "Ask AI" chat for documentation.
+   *
+   * When enabled, the unified API route handler (`/api/docs`) accepts
+   * POST requests for AI chat. The handler uses RAG (Retrieval-Augmented
+   * Generation) — it searches relevant docs, builds context, and streams
+   * a response from an LLM.
+   *
+   * The API key defaults to `process.env.OPENAI_API_KEY`. For other providers,
+   * pass the key via `apiKey: process.env.YOUR_KEY`.
+   *
+   * @example
+   * ```ts
+   * // Enable with defaults (gpt-4o-mini, OPENAI_API_KEY)
+   * ai: { enabled: true }
+   *
+   * // Custom model + system prompt
+   * ai: {
+   *   enabled: true,
+   *   model: "gpt-4o",
+   *   systemPrompt: "You are an expert on our SDK. Be concise.",
+   * }
+   *
+   * // Use a different provider (e.g. Groq)
+   * ai: {
+   *   enabled: true,
+   *   baseUrl: "https://api.groq.com/openai/v1",
+   *   apiKey: process.env.GROQ_API_KEY,
+   *   model: "llama-3.1-70b-versatile",
+   * }
+   * ```
+   */
+  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 */
@@ -632,7 +1056,7 @@ declare function createTheme(baseTheme: DocsTheme): (overrides?: Partial<DocsThe
  * @example
  * ```ts
  * import { extendTheme } from "@farming-labs/docs";
- * import { fumadocs } from "@farming-labs/fumadocs/default";
+ * import { fumadocs } from "@farming-labs/theme/default";
  *
  * // Start with fumadocs defaults, override some values
  * export const myTheme = extendTheme(fumadocs(), {
@@ -654,4 +1078,4 @@ declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): strin
  */
 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 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 LastUpdatedConfig, 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

@@ -5,6 +5,7 @@
 function defineDocs(config) {
 	return {
 		entry: config.entry ?? "docs",
+		contentDir: config.contentDir,
 		theme: config.theme,
 		nav: config.nav,
 		github: config.github,
@@ -14,6 +15,9 @@ function defineDocs(config) {
 		components: config.components,
 		icons: config.icons,
 		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		ai: config.ai,
+		ordering: config.ordering,
 		metadata: config.metadata,
 		og: config.og
 	};
@@ -81,7 +85,7 @@ function createTheme(baseTheme) {
 * @example
 * ```ts
 * import { extendTheme } from "@farming-labs/docs";
-* import { fumadocs } from "@farming-labs/fumadocs/default";
+* import { fumadocs } from "@farming-labs/theme/default";
 *
 * // Start with fumadocs defaults, override some values
 * export const myTheme = extendTheme(fumadocs(), {

package/package.json

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