API Reference

Complete reference for every option in docs.config.ts. All types are exported from @farming-labs/docs.

defineDocs(config)

The entry point for configuring your docs. Returns a typed config object.

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  // ...all options below
});

DocsConfig

Top-level configuration object passed to defineDocs().

Ordering

Controls how pages are sorted in the sidebar. Three strategies are available:

"alphabetical" (default)

Pages are sorted alphabetically by folder name. No extra configuration needed.

ordering: "alphabetical",

"numeric"

Pages are sorted by the order field in frontmatter. Lower numbers appear first. Pages without order are sorted alphabetically after ordered pages.

ordering: "numeric",

Then in your page frontmatter:

---
title: "Installation"
order: 1
---

Slug-based (OrderingItem[])

Pass an array of { slug, children? } objects for explicit control over page order, including nested pages.

ordering: [
  { slug: "installation" },
  { slug: "cli" },
  { slug: "configuration" },
  {
    slug: "themes",
    children: [
      { slug: "default" },
      { slug: "darksharp" },
      { slug: "pixel-border" },
      { slug: "creating-themes" },
    ],
  },
  {
    slug: "customization",
    children: [
      { slug: "colors" },
      { slug: "typography" },
      { slug: "sidebar" },
      { slug: "components" },
      { slug: "ai-chat" },
      { slug: "page-actions" },
    ],
  },
  { slug: "reference" },
],

OrderingItem

Pages not listed in the array appear alphabetically after the listed ones.

DocsNav

Sidebar header configuration.

nav: {
  title: "My Docs",
  url: "/docs",
},

GithubConfig

GitHub repository configuration. Enables "Edit on GitHub" links in page footers.

// Simple
github: "https://github.com/my-org/my-docs",

// Monorepo
github: {
  url: "https://github.com/my-org/monorepo",
  branch: "main",
  directory: "apps/docs/docs",
},

The "Edit on GitHub" link only appears when both url and directory are provided.

onCopyClick and CodeBlockCopyData

Optional callback on DocsConfig. Fired when the user clicks the copy button on a code block — in addition to copying to the clipboard. Use it for analytics, logging, or custom behavior. See Code block copy callback for setup (Next.js vs SvelteKit/Astro/Nuxt).

CodeBlockCopyData

Argument passed to onCopyClick(data: CodeBlockCopyData).

import type { CodeBlockCopyData } from "@farming-labs/docs";
import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  onCopyClick(data: CodeBlockCopyData) {
    // data.title, data.content, data.url, data.language
    console.log("Copied:", data.language, data.title ?? "(no title)");
  },
});

ThemeToggleConfig

Light/dark mode toggle in the sidebar.

// Show toggle (default)
themeToggle: true,

// Hide toggle, follow system preference
themeToggle: false,

// Hide toggle, force dark mode
themeToggle: { enabled: false, default: "dark" },

// Show toggle with system option
themeToggle: { mode: "light-dark-system" },

BreadcrumbConfig

Breadcrumb navigation above page content.

breadcrumb: true,              // show (default)
breadcrumb: false,             // hide
breadcrumb: { enabled: false },  // hide

SidebarConfig

Sidebar visibility and customization. See Sidebar for the full guide including custom sidebar components.

SidebarComponentProps

Props passed to a custom sidebar component:

SidebarTree

SidebarNode

A union of SidebarPageNode | SidebarFolderNode.

SidebarPageNode

SidebarFolderNode

sidebar: true,                     // show (default)
sidebar: false,                    // hide
sidebar: { collapsible: false },   // non-collapsible
sidebar: { flat: true },           // Mintlify-style flat
sidebar: {                         // custom component
  component: ({ tree }) => <MySidebar tree={tree} />,
},

DocsTheme

Theme configuration returned by theme factories.

Created via theme factories:

import { fumadocs } from "@farming-labs/theme";
import { darksharp } from "@farming-labs/theme/darksharp";
import { pixelBorder } from "@farming-labs/theme/pixel-border";
import { colorful } from "@farming-labs/theme/colorful";

theme: fumadocs({ ui: { /* overrides */ } }),

import { fumadocs, darksharp, pixelBorder } from "@farming-labs/svelte-theme";
import { colorful } from "@farming-labs/svelte-theme/colorful";

theme: fumadocs({ ui: { /* overrides */ } }),

import { fumadocs } from "@farming-labs/astro-theme";
import { pixelBorder } from "@farming-labs/astro-theme/pixel-border";
import { darksharp } from "@farming-labs/astro-theme/darksharp";
import { colorful } from "@farming-labs/astro-theme/colorful";

theme: fumadocs({ ui: { /* overrides */ } }),

import { fumadocs } from "@farming-labs/nuxt-theme/fumadocs";
import { colorful } from "@farming-labs/nuxt-theme/colorful";

theme: fumadocs({ ui: { /* overrides */ } }),

UIConfig

Fine-grained visual configuration passed to theme factories.

ColorsConfig

All color tokens. Accepts any CSS color value (hex, rgb, oklch, hsl).

colors: {
  primary: "oklch(0.72 0.19 149)",
  background: "hsl(0 0% 2%)",
  border: "#262626",
},

LayoutConfig

CodeBlockConfig

SidebarStyleConfig

TypographyConfig

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 },
    h3: { size: "1.25rem", weight: 600 },
    body: { size: "1rem", lineHeight: "1.75" },
    small: { size: "0.875rem" },
  },
},

FontStyle

Used for each heading level and body text.

AIConfig

RAG-powered AI chat. See Ask AI for usage guide.

Floating styles

PageActionsConfig

Action buttons shown on each docs page. See Page Actions for usage guide.

CopyMarkdownConfig

OpenDocsConfig

OpenDocsProvider

pageActions: {
  copyMarkdown: { enabled: true },
  openDocs: {
    enabled: true,
    providers: [
      { name: "ChatGPT", urlTemplate: "https://chatgpt.com/?q={url}" },
      { name: "Claude", urlTemplate: "https://claude.ai/new?q=Read+this:+{url}" },
    ],
  },
},

DocsMetadata

SEO metadata configuration.

metadata: {
  titleTemplate: "%s – My Docs",
  description: "Documentation for my project",
},

OGConfig

Open Graph image configuration. When endpoint is set, each docs page gets a dynamic OG image: the framework passes the page’s title and description (from frontmatter) to the endpoint, and the layout injects the resulting image URL into og:image and twitter:image meta tags. For a full guide (how dynamic OG works, what context is passed, and how the docs website implements it), see OG Images.

Example (Next.js): In docs.config.tsx, set og.endpoint to your OG route path. Then implement app/api/og/route.tsx (or route.ts) that accepts title and description query params and returns a 1200×630 image (e.g. using ImageResponse from next/og).

og: {
  enabled: true,
  type: "dynamic",
  endpoint: "/api/og",
},

Testing your OG image

1. Start the dev server for the app that serves the OG route (e.g. cd website && pnpm dev or cd examples/next && pnpm dev).
2. Open the OG URL in the browser, e.g.
   http://localhost:3000/api/og?title=Test&description=My+description
   (use your app’s port if different).
3. After changing the OG route code, refresh the page. If the image doesn’t update, do a hard refresh (e.g. Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows) or open the URL in a private/incognito window. You can also add a cache-busting query param (e.g. &_=1, &_=2) to force a new request.

Page Frontmatter

Each docs page (.mdx / .md) supports these frontmatter fields:

Static OG example — use openGraph and twitter in frontmatter to serve a static image instead of the dynamic OG endpoint:

---
title: "Title of Docs"
description: "Title of the docs goes here"
icon: "harddrive"
openGraph:
  images:
    - url: "/og/path-to-image/image.png"
      width: 1200
      height: 630
twitter:
  card: "summary_large_image"
  images:
    - "/og/path-to-image/image.png"
---

Minimal example (shorthand ogImage or generated OG):

---
title: "Getting Started"
description: "Set up your docs in 5 minutes"
icon: "rocket"
order: 1
---

Data types

Frontmatter is YAML between the --- fences. Supported value types:

You can use other YAML types (e.g. nested objects) for custom keys; only the fields in the table above are used by the framework for sidebar, SEO, and OG.

How frontmatter is passed

• Next.js — The MDX pipeline uses remark-frontmatter and remark-mdx-frontmatter with name: "metadata". The parsed frontmatter is exposed as the metadata export from the page. The layout and generateMetadata receive it when resolving the page (e.g. via getPage(params)), and it is used for createPageMetadata, sidebar tree (title, icon, order), and description maps.
• SvelteKit / Astro / Nuxt — The docs loader (e.g. import.meta.glob or content layer) reads each .md/.mdx file, parses frontmatter, and builds the nav tree and page data. Frontmatter is passed to the layout as page data (e.g. page.data or the props your content component receives). The same fields (title, description, icon, order, tags, ogImage) are used for sidebar, meta tags, and search.

So in all frameworks, the same frontmatter fields drive titles, descriptions, icons, ordering, and OG; only the mechanism (MDX metadata vs. content loader page.data) differs.

createTheme(options)

Create a custom theme from scratch. See Creating Themes.

import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-theme",
  ui: {
    colors: { primary: "#ff4d8d", background: "#0a0a0a" },
    radius: "0px",
    sidebar: { style: "bordered" },
  },
});

extendTheme(base, overrides)

Extend an existing theme with overrides.

import { extendTheme } from "@farming-labs/docs";
import { fumadocs } from "@farming-labs/theme";

export const myTheme = extendTheme(fumadocs(), {
  ui: {
    colors: { primary: "oklch(0.72 0.19 149)" },
  },
});

SvelteKit Server API

createDocsServer(config)

Creates all server-side functions for a SvelteKit docs site.

import { createDocsServer } from "@farming-labs/svelte/server";

Parameters:

Returns:

import { createDocsServer } from "@farming-labs/svelte/server";
import config from "./docs.config";

const contentFiles = import.meta.glob("/docs/**/*.{md,mdx,svx}", {
  query: "?raw",
  import: "default",
  eager: true,
}) as Record<string, string>;

export const { load, GET, POST } = createDocsServer({
  ...config,
  _preloadedContent: contentFiles,
});

SvelteKit Components

Imported from @farming-labs/svelte-theme:

Astro Server API

createDocsServer(config)

Same as SvelteKit — returns { load, GET, POST }.

import { createDocsServer } from "@farming-labs/astro/server";

Parameters:

Returns:

import { createDocsServer } from "@farming-labs/astro/server";
import config from "./docs.config";

const contentFiles = import.meta.glob("/docs/**/*.{md,mdx}", {
  query: "?raw",
  import: "default",
  eager: true,
}) as Record<string, string>;

export const { load, GET, POST } = createDocsServer({
  ...config,
  _preloadedContent: contentFiles,
});

Astro Components

CSS Imports

Same pattern as SvelteKit:

Theme Factories

Nuxt Server API

defineDocsHandler(config, useStorage)

Creates a single Nitro event handler that serves docs loading, search, and AI chat for Nuxt.

import { defineDocsHandler } from "@farming-labs/nuxt/server";

Parameters:

Returns:

A Nitro event handler that responds to GET (page loading + search) and POST (AI chat) requests.

import { defineDocsHandler } from "@farming-labs/nuxt/server";
import config from "../../docs.config";

export default defineDocsHandler(config, useStorage);

Nuxt uses Nitro's serverAssets to load markdown files. Configure nitro.serverAssets in nuxt.config.ts to point to your docs directory.

Nuxt Components

Imported from @farming-labs/nuxt-theme:

CSS Imports

Theme Factories

Next.js API

RootProvider

Client-side provider that wraps your entire app. Enables search, theme switching (light/dark), and AI chat. Must be placed in your root app/layout.tsx.

import { RootProvider } from "@farming-labs/theme";
import "./global.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <RootProvider>{children}</RootProvider>
      </body>
    </html>
  );
}

suppressHydrationWarning on <html> prevents React warnings caused by the theme class being injected before hydration.

withDocs(nextConfig)

Wraps your Next.js config with docs framework support. Handles MDX, routing, search index generation, and auto-generates mdx-components.tsx and app/docs/layout.tsx if missing.

import { withDocs } from "@farming-labs/next/config";
export default withDocs({});

createDocsLayout(config)

Creates the docs layout component from your config. Auto-generated by withDocs() — you typically don't need to create this manually.

import { createDocsLayout } from "@farming-labs/theme";
import config from "@/docs.config";

const { DocsLayout } = createDocsLayout(config);

export default function Layout({ children }) {
  return <DocsLayout>{children}</DocsLayout>;
}