@farming-labs/docs 0.0.2-beta.9 → 0.0.2

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 {
   /**
@@ -288,6 +297,54 @@ interface BreadcrumbConfig {
    */
   component?: unknown;
 }
+/**
+ * A leaf page in the sidebar tree.
+ */
+interface SidebarPageNode {
+  type: "page";
+  name: string;
+  url: string;
+  icon?: unknown;
+}
+/**
+ * A folder (group) in the sidebar tree. May contain child pages
+ * and nested folders, forming a recursive hierarchy.
+ */
+interface SidebarFolderNode {
+  type: "folder";
+  name: string;
+  icon?: unknown;
+  /** Index page for this folder (the folder's own landing page). */
+  index?: SidebarPageNode;
+  /** Child pages and sub-folders. */
+  children: SidebarNode[];
+  /** Whether this folder section is collapsible. */
+  collapsible?: boolean;
+  /** Whether this folder starts open. */
+  defaultOpen?: boolean;
+}
+/** A node in the sidebar tree — either a page or a folder. */
+type SidebarNode = SidebarPageNode | SidebarFolderNode;
+/** The full sidebar tree passed to custom sidebar components. */
+interface SidebarTree {
+  name: string;
+  children: SidebarNode[];
+}
+/**
+ * Props passed to a custom sidebar component.
+ *
+ * Contains all the information needed to build a fully custom sidebar:
+ * the complete page tree with parent-child relationships, and the
+ * current sidebar configuration.
+ */
+interface SidebarComponentProps {
+  /** Full page tree with all parent-child-folder relationships. */
+  tree: SidebarTree;
+  /** Whether folders are collapsible. */
+  collapsible: boolean;
+  /** Whether folders are rendered flat (Mintlify-style). */
+  flat: boolean;
+}
 interface SidebarConfig {
   /**
    * Whether to show the sidebar.
@@ -295,17 +352,46 @@ interface SidebarConfig {
    */
   enabled?: boolean;
   /**
-   * Custom sidebar component to completely replace the default sidebar.
-   * Receives the page tree and config as context.
+   * Custom sidebar component to replace the default navigation.
    *
-   * @example
+   * **Next.js** — Pass a render function that receives `SidebarComponentProps`:
    * ```tsx
    * sidebar: {
-   *   component: MySidebar,
+   *   component: ({ tree, collapsible, flat }) => (
+   *     <MySidebar tree={tree} />
+   *   ),
    * }
    * ```
+   *
+   * **Astro** — Use the `sidebar` named slot on `<DocsLayout>`:
+   * ```astro
+   * <DocsLayout tree={tree} config={config}>
+   *   <MySidebar slot="sidebar" tree={tree} />
+   *   <slot />
+   * </DocsLayout>
+   * ```
+   *
+   * **SvelteKit** — Use the `sidebar` snippet on `<DocsLayout>`:
+   * ```svelte
+   * <DocsLayout {tree} {config}>
+   *   {#snippet sidebar({ tree, isActive })}
+   *     <MySidebarNav {tree} {isActive} />
+   *   {/snippet}
+   *   {@render children()}
+   * </DocsLayout>
+   * ```
+   *
+   * **Nuxt / Vue** — Use the `#sidebar` scoped slot on `<DocsLayout>`:
+   * ```vue
+   * <DocsLayout :tree="tree" :config="config">
+   *   <template #sidebar="{ tree, isActive }">
+   *     <MySidebarNav :tree="tree" :is-active="isActive" />
+   *   </template>
+   *   <DocsContent />
+   * </DocsLayout>
+   * ```
    */
-  component?: unknown;
+  component?: (props: SidebarComponentProps) => unknown;
   /**
    * Sidebar footer content (rendered below navigation items).
    */
@@ -319,6 +405,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.
@@ -334,10 +431,13 @@ interface OpenDocsProvider {
   /** 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.
+   * URL template. Placeholders:
+   * - `{url}` — current page URL (encoded).
+   * - `{mdxUrl}` — page URL with `.mdx` suffix (encoded).
+   * - `{githubUrl}` — GitHub edit URL for the current page (same as "Edit on GitHub"). Requires `github` in config.
    *
    * @example "https://claude.ai/new?q=Read+this+doc:+{url}"
+   * @example "{githubUrl}" — open current page file on GitHub (edit view)
    */
   urlTemplate: string;
 }
@@ -404,6 +504,65 @@ 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" }
+ * ```
+ */
+/**
+ * Configuration for auto-generated `/llms.txt` and `/llms-full.txt` routes.
+ *
+ * @see https://llmstxt.org
+ */
+interface LlmsTxtConfig {
+  /**
+   * Whether to enable llms.txt generation.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Base URL for your docs site (used to build absolute links in llms.txt).
+   * @example "https://docs.example.com"
+   */
+  baseUrl?: string;
+  /**
+   * Site title shown at the top of llms.txt.
+   * Falls back to `nav.title` if not set.
+   */
+  siteTitle?: string;
+  /**
+   * Site description shown below the title.
+   */
+  siteDescription?: string;
+}
+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
@@ -487,7 +646,7 @@ interface AIConfig {
    * }
    * ```
    */
-  mode?: "search" | "floating";
+  mode?: "search" | "floating" | "sidebar-icon";
   /**
    * Position of the floating chat button on screen.
    * Only used when `mode` is `"floating"`.
@@ -531,19 +690,44 @@ interface AIConfig {
    */
   floatingStyle?: "panel" | "modal" | "popover" | "full-modal";
   /**
-   * Custom trigger component for the floating chat button.
+   * Custom trigger component for the floating chat button (Next.js only).
    * Only used when `mode` is `"floating"`.
    *
-   * Pass a React element to replace the default sparkles button.
-   * The element receives an `onClick` handler automatically.
+   * The click handler is attached automatically by the wrapper.
+   *
+   * - **Next.js**: Pass a JSX element via this config option.
+   * - **SvelteKit**: Use the `aiTrigger` snippet on `<DocsLayout>`.
+   * - **Nuxt / Vue**: Use the `ai-trigger` slot on `<DocsLayout>`.
+   * - **Astro**: Use `<MyTrigger slot="ai-trigger" />` on `<DocsLayout>`.
    *
    * @example
    * ```tsx
-   * ai: {
-   *   enabled: true,
-   *   mode: "floating",
-   *   triggerComponent: <button className="my-chat-btn">💬 Help</button>,
-   * }
+   * // Next.js — pass JSX directly in config
+   * triggerComponent: <button className="my-chat-btn">Ask AI</button>,
+   * ```
+   *
+   * ```svelte
+   * <!-- SvelteKit — use snippet in layout -->
+   * <DocsLayout {tree} {config}>
+   *   {#snippet aiTrigger()}<AskAITrigger />{/snippet}
+   *   {@render children()}
+   * </DocsLayout>
+   * ```
+   *
+   * ```vue
+   * <!-- Nuxt / Vue — use named slot in layout -->
+   * <DocsLayout :tree="tree" :config="config">
+   *   <template #ai-trigger><AskAITrigger /></template>
+   *   <DocsContent />
+   * </DocsLayout>
+   * ```
+   *
+   * ```astro
+   * <!-- Astro — use named slot in layout -->
+   * <DocsLayout tree={tree} config={config}>
+   *   <AskAITrigger slot="ai-trigger" />
+   *   <DocsContent />
+   * </DocsLayout>
    * ```
    */
   triggerComponent?: unknown;
@@ -653,11 +837,37 @@ interface AIConfig {
    */
   docsUrl?: string;
   /**
-   * Custom loading indicator shown while the AI is generating a response.
-   * Replaces the default "AI is thinking..." indicator.
+   * Loading indicator variant shown while the AI generates a response.
    *
-   * Pass a function that receives `{ name }` (the `aiLabel` value) and
-   * returns a React element. This way you don't need to duplicate the label.
+   * - `"shimmer-dots"` — shimmer text + typing dots (default)
+   * - `"circular"` — spinning ring
+   * - `"dots"` — bouncing dots
+   * - `"typing"` — typing dots
+   * - `"wave"` — wave bars
+   * - `"bars"` — thick wave bars
+   * - `"pulse"` — pulsing ring
+   * - `"pulse-dot"` — pulsing dot
+   * - `"terminal"` — blinking terminal cursor
+   * - `"text-blink"` — blinking text
+   * - `"text-shimmer"` — shimmer text only
+   * - `"loading-dots"` — "Thinking..." with animated dots
+   *
+   * @default "shimmer-dots"
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   loader: "wave",
+   * }
+   * ```
+   */
+  loader?: "shimmer-dots" | "circular" | "dots" | "typing" | "wave" | "bars" | "pulse" | "pulse-dot" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
+  /**
+   * Custom loading indicator that overrides the built-in `loader` variant.
+   * Receives `{ name }` (the `aiLabel` value) and returns a React element.
+   *
+   * Only works in Next.js. For other frameworks, use the `loader` option.
    *
    * @example
    * ```tsx
@@ -677,6 +887,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;
@@ -816,6 +1050,24 @@ 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.
    *
@@ -849,6 +1101,55 @@ 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[];
+  /**
+   * Auto-generate `/llms.txt` and `/llms-full.txt` routes for LLM-friendly
+   * documentation. These files let AI tools quickly understand your docs.
+   *
+   * @example
+   * ```ts
+   * llmsTxt: {
+   *   enabled: true,
+   *   baseUrl: "https://docs.example.com",
+   * }
+   * ```
+   *
+   * @see https://llmstxt.org
+   */
+  llmsTxt?: boolean | LlmsTxtConfig;
   /** SEO metadata - separate from theme */
   metadata?: DocsMetadata;
   /** Open Graph image handling */
@@ -924,4 +1225,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 LastUpdatedConfig, type LlmsTxtConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -15,7 +15,10 @@ function defineDocs(config) {
 		components: config.components,
 		icons: config.icons,
 		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		llmsTxt: config.llmsTxt,
 		ai: config.ai,
+		ordering: config.ordering,
 		metadata: config.metadata,
 		og: config.og
 	};

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.2-beta.9",
+  "version": "0.0.2",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
+  "keywords": [
+    "docs",
+    "documentation",
+    "mdx"
+  ],
+  "license": "MIT",
+  "author": "Farming Labs",
+  "bin": {
+    "docs": "./dist/cli/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -13,19 +26,6 @@
       "default": "./dist/index.mjs"
     }
   },
-  "bin": {
-    "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",