--- title: "API Reference" description: "Complete reference for all configuration options" canonical_url: "https://docs.farming-labs.dev/docs/reference" markdown_url: "https://docs.farming-labs.dev/docs/reference.md" last_updated: "2026-10-17" agent: tokenBudget: 1800 task: "Select and configure the exact typed Farming Labs docs option required by a project." outcome: "The chosen defineDocs option has the documented type and default and the resolved runtime exposes matching behavior." appliesTo: framework: - "nextjs" - "tanstackstart" - "sveltekit" - "astro" - "nuxt" version: - ">=0.2.60" package: - "@farming-labs/docs" prerequisites: - "Identify the project framework and the exact capability being configured." - "Read the existing docs.config before changing nested options or callbacks." files: - "docs.config.ts" - "docs.config.tsx" - "src/lib/docs.config.ts" commands: - run: "pnpm exec docs doctor --agent" description: "Resolve config and compare discovery metadata with the public schema." verification: - run: "pnpm exec docs doctor --agent" expect: "Config loading confidence and discovery/config/schema consistency pass after the option change." - description: "Query MCP get_config_schema for the changed option." expect: "The returned type, default, and description match the option used in docs.config." rollback: - "Restore the previous option value and any route wiring or environment variables added with it." failureModes: - symptom: "TypeScript rejects a documented option." resolution: "Confirm all Farming Labs packages use the same version and use docs.config.tsx when JSX is present." - symptom: "The config accepts an option but discovery advertises a different capability state." resolution: "Run the agent doctor and update stale adapter or static-export artifacts from the resolved config." --- ## Agent Contract Task: Select and configure the exact typed Farming Labs docs option required by a project. Outcome: The chosen defineDocs option has the documented type and default and the resolved runtime exposes matching behavior. ### Applies To - Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt` - Version: `>=0.2.60` - Package: `@farming-labs/docs` ### Prerequisites - Identify the project framework and the exact capability being configured. - Read the existing docs.config before changing nested options or callbacks. ### Files - `docs.config.ts` - `docs.config.tsx` - `src/lib/docs.config.ts` ### Commands - `pnpm exec docs doctor --agent` — Resolve config and compare discovery metadata with the public schema. ### Verification - Run `pnpm exec docs doctor --agent` - Expected: Config loading confidence and discovery/config/schema consistency pass after the option change. - Query MCP get_config_schema for the changed option. - Expected: The returned type, default, and description match the option used in docs.config. ### Rollback - Restore the previous option value and any route wiring or environment variables added with it. ### Failure Modes - TypeScript rejects a documented option. — Recovery: Confirm all Farming Labs packages use the same version and use docs.config.tsx when JSX is present. - The config accepts an option but discovery advertises a different capability state. — Recovery: Run the agent doctor and update stale adapter or static-export artifacts from the resolved config. # API Reference URL: /docs/reference LLM index: /llms.txt Description: Complete reference for all configuration options Related: /docs/configuration, /docs/cli, /docs/installation, /docs/customization/mcp Inspect the existing `defineDocs()` call and select the exact exported `DocsConfig` field documented below. Config path: `docs.config.ts[x]` for Next.js, TanStack Start, and Nuxt; `src/lib/docs.config.ts` for SvelteKit and Astro. Non-Next adapters can configure `contentDir` and `nav` explicitly; Next.js derives its content tree from `app/{entry}/`. When MCP `get_config_schema` publishes the option, compare its type and default; otherwise verify against installed exported types. Run `pnpm exec docs doctor --agent` for resolved capability and discovery fields. For SvelteKit or Astro, append `--config src/lib/docs.config.ts`. If TypeScript rejects the documented shape, align all `@farming-labs/*` package versions and rename config to `.tsx` when it contains JSX. If diagnostics and public discovery disagree, restore the previous value and repair the adapter route or stale static export before re-enabling. All types exported from `@farming-labs/docs`. Farm.js adapter options are exported from `@farming-labs/farmjs`. Its `withDocs(farmConfig, options)` and lower-level `docsMdx(options)` accept `buildCache` (boolean, default `true`). Production builds outside watch mode reuse unchanged MDX compilation and highlighting in `/farming-docs/mdx-v1.json`, normally `node_modules/.vite/farming-docs/mdx-v1.json`. Preserve this directory in CI for repeated builds. Source, module path, themes, mode, Node version, and compiler implementation changes invalidate cached output. Missing or unusable caches fall back to compilation; set `buildCache: false` to diagnose without reuse. --- ## `defineDocs(config)` ```ts title="docs.config.ts" import { defineDocs } from "@farming-labs/docs"; export default defineDocs({ entry: "docs", // ...all options below }); ``` --- ## `DocsConfig` ### `DocsLocalMcpSearchRuntimeConfig` Runtime shape for whether the local MCP server is the search target. Exported from `@farming-labs/docs` and `@farming-labs/docs/server`. | Property | Type | Description | | -------- | ---- | ----------- | | `enabled` | `boolean` | Whether the local MCP server is enabled | | `route` | `string` | Canonical HTTP route for the local MCP endpoint (e.g. `"/api/docs/mcp"`) | | `tools` | `{ searchDocs?: boolean }` | `searchDocs` controls whether `search_docs` is exposed | ### `DocsLocalMcpSearchRuntimeInput` Accepted input for `resolveLocalDocsMcpSearchConfig`. Partial form of `DocsLocalMcpSearchRuntimeConfig` — all fields optional. Exported from `@farming-labs/docs` and `@farming-labs/docs/server`. ### `DocsSearchRequestResolutionOptions` Options for the third parameter of `resolveSearchRequestConfig`. Exported from `@farming-labs/docs` and `@farming-labs/docs/server`. | Property | Type | Description | | -------- | ---- | ----------- | | `localMcp` | `DocsLocalMcpSearchRuntimeInput \| null \| undefined` | When present, calls `resolveLocalDocsMcpSearchConfig` before the self-referential URL check | ### `resolveLocalDocsMcpSearchConfig` Exported from `@farming-labs/docs` and `@farming-labs/docs/server`. Given a `McpDocsSearchConfig`, optional `DocsLocalMcpSearchRuntimeInput`, and optional request URL, returns a modified search config using direct simple search when the configured MCP endpoint resolves to the local server. Returns original config unchanged for external endpoints. ```ts import { resolveLocalDocsMcpSearchConfig } from "@farming-labs/docs"; const resolved = resolveLocalDocsMcpSearchConfig( search, // McpDocsSearchConfig mcp, // DocsLocalMcpSearchRuntimeInput | null | undefined requestUrl, // string | undefined ); ``` `resolveSearchRequestConfig` accepts an optional third `options: DocsSearchRequestResolutionOptions` argument. Pass `{ localMcp: config.mcp }` to enable local-MCP detection in custom server adapters. Top-level configuration object passed to `defineDocs()`: | Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | `entry` | `string` | **required** | Docs source route and folder (e.g. `"docs"` -> `app/docs`) | | `docsPath` | `string` | same as `entry` | Public docs route prefix in Next.js. Use `""` to serve docs from `/` | | `contentDir` | `string` | same as `entry` | Path to content files. TanStack Start, SvelteKit, Astro, and Nuxt use it; Next.js uses `app/{entry}/` | | `staticExport` | `boolean` | `false` | `true` for full static builds; hides search and AI | | `theme` | `DocsTheme` | — | Theme preset (`fumadocs()`, `darksharp()`, `pixelBorder()`, etc.) | | `github` | `string \| GithubConfig` | — | GitHub repo config for "Edit on GitHub" links | | `nav` | `DocsNav` | — | Sidebar header title and URL | | `themeToggle` | `boolean \| ThemeToggleConfig` | `true` | Light/dark mode toggle | | `breadcrumb` | `boolean \| BreadcrumbConfig` | `true` | Breadcrumb navigation | | `sidebar` | `boolean \| SidebarConfig` | `true` | Sidebar visibility and customization | | `icons` | `Record` | — | Shared icon registry for frontmatter `icon` fields and built-ins like `Prompt` | | `components` | `Record` | — | Custom MDX component overrides including built-ins like `HoverLink` and `Prompt` | | `analytics` | `boolean \| DocsAnalyticsConfig` | `false` | Product/usage event stream for docs UI, search, AI, feedback, agent reads | | `apiReference` | `boolean \| ApiReferenceConfig` | `false` | Generate an API reference from framework routes or an OpenAPI contract | ### `ApiReferenceConfig.renderer` `renderer` accepts `"farming-labs"`, `"scalar"`, `"fumadocs"`, or a `{ name, options }` renderer object. The native `"farming-labs"` renderer is the default on Next.js, TanStack Start, Farm.js, SvelteKit, Astro, and Nuxt. It renders the shared normalized operation model with searchable grouped navigation, version switching, stable operation permalinks, parameters, schemas, responses, authentication metadata, copyable cURL examples, and a browser-based **Try it** console. The console supports server, path/query/header parameter, JSON/raw body, browser credential, bearer/basic, and API-key inputs; credentials stay in memory. Mutating methods require explicit confirmation and cross-origin APIs must allow the docs origin through CORS. Relative servers resolve against the docs origin. Use `"scalar"` as a bundled alternate on any framework or `"fumadocs"` on Next.js; those renderers keep their own request tooling. Next.js also exports `fumadocsRenderer()` from `@farming-labs/next/fumadocs-renderer`; it type-checks upstream playground/runtime options, including custom `authProviders`, OAuth redirect and proxy URLs, response schema behavior, and schema UI. Provider callbacks run in the browser and must not contain secrets. Next.js and Farm.js serve the configured API-reference route through `withDocs()`. TanStack Start, SvelteKit, Astro, and Nuxt still require their generated `/{path}` route handlers. ### `ApiReferenceConfig.specUrl` Set `specUrl` to a project-relative JSON/YAML file, a `file:` URL, an absolute HTTP(S) URL, or a request-relative URL such as `/api/openapi.json`. Setting it disables framework route scanning. Local filesystem paths are not published through discovery metadata. Sources must use Swagger 2.0 or OpenAPI 3.0.x, 3.1.x, or 3.2.x. Internal and external `$ref` URI references with JSON Pointer fragments are bundled once per build. Each document is limited to 5 MiB, a build can load at most 32 documents, and remote requests time out after 10 seconds. Project-relative sources and their references must stay inside the project root; an explicit `file:` URL opts into a trusted external local file. Named anchors and `$dynamicRef` are not resolved yet. Server integrations can import `buildNormalizedOpenApiModel` and `NormalizedOpenApi*` types from `@farming-labs/docs/server` for the stable operation IDs/slugs, tags, parameters, schemas, examples, servers, and security metadata used by OpenAPI-backed projections. For multiple contracts, set `apiReference.versions` to a record of URL-safe version keys and set `apiReference.defaultVersion` to one of those keys. Do not combine `versions` with `specUrl` or top-level `overlays`. Each version is rendered at `/{path}/{version}` and served at `/api/docs?format=openapi&version={version}`; unversioned routes resolve the default. Discovery, llms, and the RFC 9727 API catalog publish every version. Use ordered `apiReference.overlays` with a single `specUrl`, or `overlays` inside an individual version. Local and remote JSON/YAML Overlay 1.0.x and 1.1.x documents are supported. Actions run in declared order, target RFC 9535 JSONPath nodes, and apply before `$ref` resolution. Invalid overlay documents, selectors, unmatched targets, incompatible merges, and invalid final contracts are reported. Overlay sources inherit contract timeout, size, and project-root containment rules. Page-level metadata for machine-readable docs workflows: | Property | Type | Description | | --- | --- | --- | | `tokenBudget` | `number` | Approximate output token target for `docs agent compact` on this page | | `task` | `string` | Concrete task the page helps an agent complete | | `outcome` | `string` | Observable end state indicating completion | | `appliesTo` | `{ framework?, version?, package? }` | Each accepts a string or string array | | `prerequisites` | `string[]` | Setup or conditions that must already be true | | `files` | `string[]` | Files the task is expected to read or change | | `commands` | `(string \| PageAgentCommand)[]` | Command strings or `{ run, cwd?, description? }` objects | | `sideEffects` | `string[]` | Material state changes or external effects | | `verification` | `(string \| PageAgentVerification)[]` | Checks or `{ description?, run?, expect? }` objects | | `rollback` | `string[]` | Steps that restore the prior state | | `failureModes` | `(string \| PageAgentFailureMode)[]` | Symptoms or `{ symptom, resolution? }` objects | ## PageAgentFrontmatter field types `PageAgentFrontmatter` defines `task`, `outcome`, `appliesTo`, `prerequisites`, `verification`, `rollback`, and `failureModes`; every structured failure mode pairs a `symptom` with its `resolution`. ## PageAgentFrontmatter failureModes resolution In `page-frontmatter.md`, use `failureModes` for recoverable failures. The exact example resolves a missing route with `resolution: Confirm withDocs wraps the Next.js config`. ```md title="page-frontmatter.md" --- title: "Installation" agent: task: Install the framework outcome: The docs route renders locally. failureModes: - symptom: The route returns 404 resolution: Confirm withDocs wraps the Next.js config --- ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).