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().

components is merged into the default MDX component map, so you can both add your own components and replace built-ins such as Callout, Tabs, HoverLink, or Prompt. For built-in defaults like theme.ui.components.HoverLink and theme.ui.components.Prompt, see Creating themes. For usage examples and a live demo, see Components.

analytics and DocsAnalyticsConfig

Built-in product and usage event stream. Use it for page views, search activity, Ask AI request counts, feedback, page actions, machine-readable markdown reads, agent feedback routes, and MCP usage. See Analytics for the full guide and event list.

analytics: {
  onEvent(event) {
    console.info(event.type, event.properties);
  },
}

observability and DocsObservabilityConfig

Built-in trace event stream for agent runtime debugging. Use it for Ask AI and MCP spans, timing, status, previews, errors, retries, and final handoffs. See Observability for the full guide and trace event list.

observability: {
  console: "debug",
  onEvent(event) {
    console.info(event.type, event.traceId, event.durationMs);
  },
}

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",
},

LlmsTxtConfig

Generated llms.txt files for agent-readable docs indexes. The root files are enabled by default; section files are opt-in and only add route handling plus discovery metadata. If a native static file already exists at the same public route, such as public/llms.txt or SvelteKit static/llms.txt, that file takes precedence and the generated output remains the fallback.

export default defineDocs({
  llmsTxt: {
    baseUrl: "https://docs.example.com",
    maxChars: {
      mode: "warn",
      chars: 50_000,
    },
    sections: [
      {
        title: "API",
        description: "Endpoint, SDK, and integration reference pages.",
        match: "/docs/api/**",
        maxChars: {
          mode: "warn",
          chars: 25_000,
        },
      },
    ],
  },
});

Default routes:

• /llms.txt
• /llms-full.txt
• /.well-known/llms.txt
• /.well-known/llms-full.txt

For sections, the route is derived from the first match value. For example, /docs/api/** creates /docs/api/llms.txt and /docs/api/llms-full.txt. Root /llms.txt lists configured sections first and keeps matching pages inside those section files.

LlmsTxtMaxCharsConfig

LlmsTxtSectionConfig

DocsMcpConfig

Built-in MCP server configuration for AI clients, IDE agents, and local MCP tooling.

export default defineDocs({
  entry: "docs",
  mcp: {
    route: "/api/docs/mcp",
    name: "My Docs MCP",
    tools: {
      listPages: true,
      getNavigation: true,
      searchDocs: true,
      readPage: true,
    },
  },
});

DocsMcpToolsConfig

Default MCP surface:

• Public HTTP route: /mcp
• Well-known HTTP route: /.well-known/mcp
• Canonical HTTP route: /api/docs/mcp
• stdio command: pnpx @farming-labs/docs mcp
• Built-in tools: list_pages, get_navigation, search_docs, read_page

Framework notes:

• Next.js: withDocs() auto-generates the default /api/docs/mcp route and public /mcp plus /.well-known/mcp rewrites
• TanStack Start / SvelteKit / Astro / Nuxt: use the generated public forwarder for MCP aliases, or add an equivalent framework hook/middleware that forwards to the built-in MCP handler
• Custom routes: set mcp.route in docs.config and update the framework public forwarder so the configured path and the actual endpoint stay aligned

See MCP Server for the route snippets and examples.

DocsRobotsConfig

Runtime and generated robots.txt policy for docs and agent-readable routes. Server-rendered apps serve /robots.txt through the shared docs handler when no static file already owns that path; the CLI writes or appends a static file for static export and committed policies.

export default defineDocs({
  robots: {
    enabled: true,
    baseUrl: "https://docs.example.com",
    path: "public/robots.txt",
    ai: "allow",
  },
});

Generated policy covers the docs entry, .md routes, llms.txt, sitemap routes, AGENTS.md, skill.md, MCP aliases, agent discovery routes, and common AI crawler user agents. Existing files are preserved by default; use docs robots generate --append to add or update the managed block, or --force to replace the file.

The agent discovery JSON advertises this surface as robots.enabled, robots.route, and robots.defaultRoute, so agents can find the policy without guessing.

DocsRobotsRule

See CLI for docs robots generate and Configuration for the high-level setup guide.

DocsSearchConfig

Search is enabled by default. If you do not configure anything, the docs API uses the built-in simple adapter with section-based chunking.

export default defineDocs({
  entry: "docs",
  search: true,
});

Built-in providers:

• simple — zero-config docs search with section chunking
• typesense — external Typesense collection with optional hybrid mode
• algolia — external Algolia index
• mcp — Streamable HTTP MCP endpoint that exposes a search_docs tool
• custom — your own adapter implementation

SimpleDocsSearchConfig

search: {
  provider: "simple",
  maxResults: 8,
  chunking: {
    strategy: "section",
  },
},

TypesenseDocsSearchConfig

search: {
  provider: "typesense",
  baseUrl: process.env.TYPESENSE_URL!,
  collection: "docs",
  apiKey: process.env.TYPESENSE_SEARCH_API_KEY!,
  adminApiKey: process.env.TYPESENSE_ADMIN_API_KEY,
  mode: "hybrid",
  embeddings: {
    provider: "ollama",
    model: "embeddinggemma",
  },
},

pnpm dlx @farming-labs/docs search sync --typesense

AlgoliaDocsSearchConfig

search: {
  provider: "algolia",
  appId: process.env.ALGOLIA_APP_ID!,
  indexName: "docs",
  searchApiKey: process.env.ALGOLIA_SEARCH_API_KEY!,
  adminApiKey: process.env.ALGOLIA_ADMIN_API_KEY,
},

pnpm dlx @farming-labs/docs search sync --algolia

McpDocsSearchConfig

search: {
  provider: "mcp",
  endpoint: "/mcp",
},

Relative endpoints are resolved against the current docs API request URL. That makes local setups like the Next example easy to test without hardcoding a host.

CustomDocsSearchConfig

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

export default defineDocs({
  entry: "docs",
  search: createCustomSearchAdapter({
    name: "my-search",
    async search(query, context) {
      return context.documents
        .filter((doc) =>
          `${doc.title} ${doc.section ?? ""} ${doc.content}`.toLowerCase().includes(query.query.toLowerCase()),
        )
        .slice(0, query.limit ?? 10)
        .map((doc) => ({
          id: doc.id,
          url: doc.url,
          content: doc.section ? `${doc.title} — ${doc.section}` : doc.title,
          description: doc.description,
          type: doc.type,
          section: doc.section,
        }));
    },
  }),
});

DocsSearchAdapter

Custom adapters receive normalized source pages and chunked search documents so you can focus on retrieval and ranking instead of rebuilding the docs scan pipeline.

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

export const adapter: DocsSearchAdapter = {
  name: "my-search",
  async search(query, context) {
    return context.documents.map((doc) => ({
      id: doc.id,
      url: doc.url,
      content: doc.section ? `${doc.title} — ${doc.section}` : doc.title,
      description: doc.description,
      type: doc.type,
      section: doc.section,
    }));
  },
};

DocsSearchChunkingConfig

DocsSearchEmbeddingsConfig

Notes:

• search: false disables search entirely
• Search requires the docs API route; static export hides the UI because there is no server route
• On Next.js, generated routes from withDocs() pass docsConfig directly into createDocsAPI
• MCP-backed search works with relative endpoints like /mcp or /.well-known/mcp and absolute remote endpoints like https://docs.example.com/mcp
• If MCP-backed search points at the same relative MCP route, the built-in search_docs tool falls back to simple search internally to avoid recursive loops
• On custom/manual Next routes, import createDocsAPI from @farming-labs/next/api and pass the whole config: createDocsAPI(docsConfig)

ApiReferenceConfig

Generates API reference pages from framework route conventions or a hosted OpenAPI JSON document.

Use route scanning when the API lives in the same project. Use specUrl when the backend is deployed elsewhere and already exposes an openapi.json.

apiReference: {
  enabled: true,
  path: "api-reference",
  routeRoot: "api",
  exclude: ["/api/internal/health", "internal/debug"],
},

apiReference: {
  enabled: true,
  path: "api-reference",
  specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
},

When specUrl is set, routeRoot and exclude are ignored and the API reference is rendered from the hosted spec instead.

This does not remove the framework route requirement on non-Next adapters. TanStack Start, SvelteKit, Astro, and Nuxt still need their /{path} handler files so the docs app has a route that serves the generated API reference page.

When output: "export" is used in Next.js, the generated API reference route is skipped automatically because it requires a server route handler.

Scanned route conventions:

• Next.js: app/api/**/route.ts and src/app/api/**/route.ts
• TanStack Start: src/routes/api.*.ts and nested route files inside the configured route root
• SvelteKit: src/routes/api/**/+server.ts or +server.js
• Astro: src/pages/api/**/*.ts or .js
• Nuxt: server/api/**/*.ts or .js

Minimal route handlers for non-Next frameworks:

import { createFileRoute } from "@tanstack/react-router";
import { createTanstackApiReference } from "@farming-labs/tanstack-start/api-reference";
import docsConfig from "../../docs.config";

const handler = createTanstackApiReference(docsConfig);

export const Route = createFileRoute("/api-reference/")({
  server: {
    handlers: {
      GET: handler,
    },
  },
});

Create a second src/routes/api-reference.$.ts file with the same handler and createFileRoute("/api-reference/$").

import { createSvelteApiReference } from "@farming-labs/svelte/api-reference";
import config from "$lib/docs.config";

export const GET = createSvelteApiReference(config);

Create src/routes/api-reference/[...slug]/+server.ts with the same GET export.

import { createAstroApiReference } from "@farming-labs/astro/api-reference";
import config from "../../lib/docs.config";

export const GET = createAstroApiReference(config);

Create src/pages/api-reference/[...slug].ts with the same GET export.

import { defineApiReferenceHandler } from "@farming-labs/nuxt/api-reference";
import config from "~/docs.config";

export default defineApiReferenceHandler(config);

Create server/routes/api-reference/[...slug].ts with the same default export.

ChangelogConfig

Generates changelog listing and entry pages from dated MDX folders inside the docs content tree.

changelog: {
  enabled: true,
  path: "changelogs",
  contentDir: "changelog",
  title: "Changelog",
  description: "Latest product updates and release notes.",
  search: true,
},

With entry: "docs" and the config above, the public pages render at:

• /docs/changelogs
• /docs/changelogs/2026-03-04

When you use withDocs(), the route files are generated automatically. There is no separate __changelog.generated.tsx file to maintain.

ChangelogFrontmatter

Optional frontmatter fields for each changelog entry:

---
title: "OpenAPI mode is now the default"
description: "The docs example now ships with the faster API reference experience."
version: "v0.1.13"
tags: ["api-reference", "next"]
---

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 / TanStack Start 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)");
  },
});

feedback, FeedbackConfig, AgentFeedbackConfig, and feedback payloads`

Optional docs page feedback UI. When enabled, a built-in "Good / Bad" prompt is rendered at the end of the page and emits a feedback payload when the user clicks one of the buttons.

FeedbackConfig

DocsFeedbackData

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

export default defineDocs({
  entry: "docs",
  feedback: {
    enabled: true,
    onFeedback(data: DocsFeedbackData) {
      console.log("Feedback:", data.value, data.slug, data.url);
    },
  },
});

This docs site persists feedback through a local Next.js route at website/app/api/feedback/route.ts, backed by the DocsFeedback Prisma model in website/prisma/schema.prisma.

See Page feedback for framework-specific notes. The built-in UI does not require a separate client bridge file.

AgentFeedbackConfig

Optional machine-facing feedback routes for agents, scripts, or evaluation flows.

Notes:

• agent feedback routes are enabled by default; set feedback: false or feedback: { agent: false } to opt out
• feedback.agent does not enable the human footer UI by itself
• the request body always uses { context?, payload }
• without feedback.agent.onFeedback, valid submissions return { ok: true, handled: false }
• submitted feedback is not added to Ask AI prompts or docs search context by the framework
• in Next.js, withDocs() adds the public route rewrites automatically
• Astro, SvelteKit, TanStack Start, and Nuxt expose the same feedback contract through the shared /api/docs?feedback=agent query route
• the shared /api/docs handler is still the source of truth, so ?feedback=agent also works
• agents should discover site identity, locale config, capability flags, search, active markdown routes, Accept: text/markdown, Signature-Agent support, JSON-LD structured data, llms.txt, OpenAPI schema routes, sitemap routes, robots.txt, AGENTS.md, skill.md, skills, MCP, and feedback routes with GET /.well-known/agent.json; GET /.well-known/agent is the public fallback and GET /api/docs/agent/spec is the canonical framework route

DocsAgentFeedbackContext

DocsAgentFeedbackData

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

export default defineDocs({
  entry: "docs",
  feedback: {
    agent: {
      enabled: true,
      route: "/api/docs/agent/feedback",
      async onFeedback(data) {
        console.log(data.context?.page, data.payload);
      },
    },
  },
});

{
  "context": {
    "page": "/docs/installation",
    "source": "md-route"
  },
  "payload": {
    "task": "install docs in an existing Next.js app",
    "understanding": "partial",
    "outcome": "implemented",
    "confidence": 0.78
  }
}

Quick checks:

curl "http://127.0.0.1:3000/.well-known/agent.json"

curl "http://127.0.0.1:3000/AGENTS.md"

curl "http://127.0.0.1:3000/skill.md"

curl "http://127.0.0.1:3000/api/docs/agent/feedback/schema"

curl -X POST "http://127.0.0.1:3000/api/docs/agent/feedback" \
  -H "content-type: application/json" \
  -d '{"payload":{"task":"demo","outcome":"implemented"}}'

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.

Folder landing pages can still override both of those with frontmatter:

---
sidebar:
  folderIndexBehavior: "toggle"
---

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: { folderIndexBehavior: "toggle" }, // all folder parents only toggle children
sidebar: {
  folderIndexBehavior: "link",
  folderIndexBehaviorOverrides: {
    "/docs/components": "toggle",
    "/docs/customization": "toggle",
  },
},
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 } 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}" },
    ],
  },
},

ReadingTimeConfig

Estimated reading-time label shown on docs pages.

readingTime: {
  enabled: true,
  wordsPerMinute: 220,
},

Notes:

• readingTime is disabled by default until you configure it in DocsConfig
• the estimate strips code blocks, inline code, links, images, HTML, and URLs before counting
• page frontmatter can disable or override the value with readingTime: false, readingTime: true, or readingTime: 8, even when the global config is off
• placement follows the page title slot: it sits directly below the page actions row when page actions are shown above or below the title

DocsMetadata

SEO metadata configuration. Page title and description also feed the generated Schema.org JSON-LD structured data for each docs page.

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

Structured Data

Every docs page emits Schema.org JSON-LD automatically. The generated object uses @type: "TechArticle" and includes the page title, description, canonical URL, dateModified, and a BreadcrumbList.

No separate config flag is required. Absolute URLs are resolved from the first available public base URL in sitemap.baseUrl, llmsTxt.baseUrl, robots.baseUrl, or ai.docsUrl; otherwise the page route is emitted as a relative URL.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Installation",
  "description": "Install the framework",
  "url": "https://docs.example.com/docs/installation",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://docs.example.com/docs/installation"
  },
  "dateModified": "2026-05-10T00:00:00.000Z",
  "breadcrumb": {
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Docs",
        "item": "https://docs.example.com/docs"
      },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "Installation",
        "item": "https://docs.example.com/docs/installation"
      }
    ]
  }
}
</script>

The agent discovery spec advertises this as capabilities.structuredData and structuredData.schema: "https://schema.org/TechArticle".

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.ts, 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:

PageAgentFrontmatter

Page-level metadata for machine-readable docs workflows.

---
title: "Installation"
description: "Install the framework"
agent:
  tokenBudget: 777
---

Notes:

• agent.tokenBudget overrides global agent.compact.maxOutputTokens defaults and CLI --max-output-tokens for that one page
• if the page already has a sibling agent.md, docs agent compact compacts that file
• if the page does not have agent.md, the command compacts the generated machine-readable page output and writes a new sibling agent.md
• docs agent compact --changed only processes docs pages changed in the current git working tree, including staged, unstaged, and untracked docs changes
• docs agent compact --stale --include-missing will also create missing agent.md files for pages that define agent.tokenBudget
• inherited minOutputTokens is clamped down to tokenBudget when needed so the compression API never receives min_output_tokens > max_output_tokens

PageSidebarFrontmatter

Page-level sidebar metadata used while building the docs navigation tree.

---
title: "Components"
sidebar:
  folderIndexBehavior: "toggle"
---

Notes:

• this is only read from folder landing pages such as page.mdx / index.md
• it overrides global sidebar.folderIndexBehavior
• it also overrides sidebar.folderIndexBehaviorOverrides for that same folder
• folderIndexBehavior: "hidden" keeps the folder route available but omits the folder index link from the sidebar tree; in flat mode this becomes a label-only group with child links only, and direct visits to the hidden parent route redirect to the first visible child

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"
related:
  - /docs/installation
  - /docs/customization/agent-primitive
readingTime: 4
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, JSON-LD structured data, OG, search, and machine-readable markdown.

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), description maps, and JSON-LD structured data.
• TanStack Start / 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, JSON-LD structured data, and search.

So in all frameworks, the same frontmatter fields drive titles, descriptions, icons, ordering, JSON-LD, and OG; only the mechanism (MDX metadata vs. content loader page.data) differs. The related field is intentionally machine-readable first: add URL strings, and .md routes plus MCP page output render them next to Description as Related: /docs/a, /docs/b without adding a visible related-links block to the human page UI. A sibling agent.md remains a full override, so add a Related: line there manually if the override should include it.

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)" },
  },
});

TanStack Start Server API

createDocsServer(config)

Creates the TanStack Start docs server adapter.

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

Parameters:

Returns:

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

export const docsServer = createDocsServer({
  ...docsConfig,
  rootDir: process.cwd(),
});

TanStack Start Components

import { createFileRoute } from "@tanstack/react-router";
import { TanstackDocsPage } from "@farming-labs/tanstack-start/react";
import { loadDocPage } from "@/lib/docs.functions";
import docsConfig from "../../docs.config";

export const Route = createFileRoute("/docs/")({
  loader: () => loadDocPage({ data: { pathname: "/docs" } }),
  component: DocsIndexPage,
});

function DocsIndexPage() {
  const data = Route.useLoaderData();
  return <TanstackDocsPage config={docsConfig} data={data} />;
}

import { createFileRoute } from "@tanstack/react-router";
import { docsServer } from "@/lib/docs.server";

export const Route = createFileRoute("/api/docs")({
  server: {
    handlers: {
      GET: async ({ request }) => docsServer.GET({ request }),
      POST: async ({ request }) => docsServer.POST({ request }),
    },
  },
});

TanStack Start also uses the docsMdx() Vite plugin from @farming-labs/tanstack-start/vite so .mdx files compile without extra local module-loader glue.

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}", "/AGENTS.md", "/AGENT.md", "/skill.md", "/.farming-labs/sitemap-manifest.json"],
  {
    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}", "/AGENTS.md", "/AGENT.md", "/skill.md", "/.farming-labs/sitemap-manifest.json"],
  {
    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>;
}