---
title: "Configuration"
description: "Everything lives in docs.config.ts"
canonical_url: "https://docs.farming-labs.dev/docs/configuration"
markdown_url: "https://docs.farming-labs.dev/docs/configuration.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1800
  task: "Change docs.config safely for the selected framework and verify the resolved public behavior."
  outcome: "The configuration module loads successfully and the requested docs capability is reflected in diagnostics and discovery."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Identify the project framework and its documented docs.config location."
    - "Start from an existing defineDocs configuration and preserve framework-specific entry, contentDir, and nav requirements."
  files:
    - "docs.config.ts"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
  commands:
    - run: "pnpm exec docs doctor --agent"
      description: "Evaluate the config and compare it with the generated agent surface."
  verification:
    - run: "pnpm exec docs doctor --agent"
      expect: "Config loading confidence and discovery/config/schema consistency pass."
    - description: "Read /api/docs?format=diagnostics and confirm the requested capability is enabled without configuration issues."
  rollback:
    - "Restore the previous defineDocs option and any framework route wiring changed with it."
  failureModes:
    - symptom: "The config cannot be evaluated."
      resolution: "Use docs.config.tsx when the file contains JSX and fix unresolved imports or environment-dependent top-level code."
    - symptom: "Config and public discovery disagree."
      resolution: "Run the agent doctor and align the adapter route wiring with the resolved docs.config values."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Change docs.config safely for the selected framework and verify the resolved public behavior.
Outcome: The configuration module loads successfully and the requested docs capability is reflected in diagnostics and discovery.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- Identify the project framework and its documented docs.config location.
- Start from an existing defineDocs configuration and preserve framework-specific entry, contentDir, and nav requirements.

### Files

- `docs.config.ts`
- `docs.config.tsx`
- `src/lib/docs.config.ts`

### Commands

- `pnpm exec docs doctor --agent` — Evaluate the config and compare it with the generated agent surface.

### Verification

- Run `pnpm exec docs doctor --agent`
  - Expected: Config loading confidence and discovery/config/schema consistency pass.
- Read /api/docs?format=diagnostics and confirm the requested capability is enabled without configuration issues.

### Rollback

- Restore the previous defineDocs option and any framework route wiring changed with it.

### Failure Modes

- The config cannot be evaluated. — Recovery: Use docs.config.tsx when the file contains JSX and fix unresolved imports or environment-dependent top-level code.
- Config and public discovery disagree. — Recovery: Run the agent doctor and align the adapter route wiring with the resolved docs.config values.
<!-- farming-labs:agent-contract:end -->

# Configuration

You are an agent helping someone configure `@farming-labs/docs`.

Use this machine-oriented page when the user needs implementation guidance for `docs.config.ts` or `docs.config.tsx`, especially when they are asking what field to set, what defaults apply, or how a feature behaves across frameworks.

## Priorities

1. Keep the answer grounded in the actual `defineDocs()` surface.
2. Preserve exact option names:
   - `entry`
   - `theme`
   - `components`
   - `pageActions`
   - `agent`

| `contentChanges`   | `/api/docs?audience=agent&response=changes` | Body-free content synchronization feed (`docs-content-changes.v1`) |
   - `codeBlocks`
   - `search`
   - `ai`
   - `mcp`
   - `llmsTxt`
   - `sitemap`
   - `robots`
   - `apiReference`
   - `staticExport`
   - `i18n`
   - `metadata`
   - `og`
3. If the config contains JSX, prefer `docs.config.tsx`.
4. If the user only needs machine-readable page content, prefer `.md` routes or MCP `read_page` over scraping HTML.
5. For Next.js docs routes, mention `Signature-Agent` when the user wants agents to read canonical URLs as markdown.

## Guidance

- When the user wants to add a custom MDX component, point them to `components` in `defineDocs()`.
- When they want to change default props for a built-in component like `HoverLink`, point them to `theme.ui.components`.
- When they want AI-facing behavior, distinguish between:
  - `ai` for Ask AI / chat

  - `agent.contentChanges` for the body-free runtime document synchronization feed (`GET /api/docs?audience=agent&response=changes`)

  - `agent.compact` for defaults used by `docs agent compact`
  - `agent.evaluations` for golden tasks that measure retrieval, context, answers, examples, and
    budgets in `docs doctor` and `docs review`
  - `codeBlocks.validate` for planning and validating fenced MDX code blocks
  - `mcp` for the built-in MCP server, including default tools like `list_docs`, `search_docs`,
    `read_page`, `get_code_examples`, `get_config_schema`, and `get_context`
  - `llmsTxt` for crawler-friendly site summaries
  - `sitemap` for XML and Markdown maps with canonical URLs and freshness dates
  - `robots` plus `docs robots generate` for a static crawler and AI-agent access policy
  - markdown routes for page-level machine-readable content
- When they ask about generated API docs, use `apiReference`. Set `specUrl` to a project-relative
  JSON/YAML file or URL when a contract exists; otherwise use framework route scanning. The native
  `"farming-labs"` renderer is the cross-framework default and uses the normalized operation model
  for search, versions, schemas, responses, auth metadata, and cURL. Scalar remains available on
  every framework and Fumadocs on Next.js. Contracts may use Swagger 2.0 or OpenAPI 3.0–3.2;
  bounded internal/external `$ref` documents are bundled per build and project-relative files stay
  inside the project root. Use URL-safe `versions` with one `defaultVersion`, or ordered Overlay
  1.0/1.1 sources applied before reference resolution; invalid sources and targets are reported.

### Executable evaluation fixture

Use this deterministic runnable block when agent evaluations need to verify the configured
code-block runner without credentials or external services:

```js title="codeblocks-smoke.js" runnable
const metadata = { framework: "nextjs", runnable: true };

if (!metadata.runnable) {
  throw new Error("Expected runnable metadata");
}

console.log("metadata ok");
```

- When the user asks about runtime document synchronization or incremental content updates, point to `agent.contentChanges`. Enabled by default on server-rendered adapters; always `false` in static bundles produced by `docs agent export`. The endpoint is `GET /api/docs?audience=agent&response=changes` and returns a `docs-content-changes.v1` payload with `indexGeneration`, `mode` (`snapshot`, `delta`, or `reset`), `resetRequired`, `documentCount`, and `added`/`modified`/`removed` arrays. Supply `since=<indexGeneration>` from a previous response to receive a delta. ETag and `If-None-Match` conditional requests are supported.

- When they ask about static hosting, mention `staticExport: true`. Note that setting `staticExport: true` also signals to the diagnostics endpoint (`GET /api/docs?format=diagnostics`) that server-side features such as search and AI are unavailable, so diagnostics tooling can skip those checks.
- When they need to edit `docs.config.ts` through MCP, prefer `get_config_schema` before suggesting
  config changes.
- When they need compact retrieval through MCP, prefer `get_context` with an explicit token budget;
  use `read_page.section` when they already know the exact heading.
- Golden evaluations default to the local `mcp-context` surface. There is no implicit model,
  network request, or command execution. `configured-search` measures the actual `search` provider,
  and `ask-ai-context` measures the production Ask AI retrieval/context assembly path.
- Non-simple search providers and the built-in HTTP answer provider require
  `agent.evaluations.allowNetwork: true`. Provider failures fail the task instead of falling back to
  local search. `searchTimeoutMs` defaults to 30 seconds per retrieval attempt; transient timeouts,
  fetch failures, rate limits, and server errors are retried twice with bounded backoff. Optional
  HTTP authentication belongs in `answer.headers`; header values are never included in reports.
- An answer provider is opt-in. Use `{ provider: "callback", run }` for explicit user code or
  `{ provider: "http", endpoint, headers?, timeoutMs? }` for the managed HTTP contract. Add
  `expect.answer` only when answer text and answer citations should be scored; context citations are
  reported as context evidence, not mislabeled as model-answer citations.
- `filters` constrain retrieval. Use `expect.scope` to assert returned framework, version, or locale
  without pre-filtering away a wrong result.
- Expected examples support `verification: "present" | "syntax" | "execute"`. Runnable examples
  default to syntax, non-runnable examples default to presence, and execution requires an explicit
  execute expectation, `allowNetwork: true`, and enabled `codeBlocks.validate` report mode. Skips
  never count as passes.
- When they ask about reading time, note that `readingTime` is opt-in (`enabled: true` required).
  The `includeCode` field inside `ReadingTimeConfig` defaults to `false`, which means fenced and
  inline code blocks are stripped before counting words so the label reflects human prose length.
  Recommend `includeCode: true` only for code-heavy guides where examples make up a large part of
  the page and should count toward the estimate. Do not recommend setting it globally when prose
  length is the primary signal the team cares about.
- When the user asks which routes are available to agents, include `GET /api/docs?format=diagnostics` alongside `GET /api/docs?format=config`. The agent discovery spec (served at `/.well-known/agent.json`) now includes a `diagnostics` key pointing to `/api/docs?format=diagnostics`. That endpoint returns a `DocsDiagnostics` payload (format: `"docs-diagnostics.v1"`) describing enabled features and any configuration issues. All five framework adapters handle this route automatically — no additional setup is required.
- Include `GET`/`HEAD /.well-known/api-catalog` for RFC 9727 API discovery and
  `GET`/`HEAD /.well-known/agent-skills/index.json` for SHA-256 Agent Skills discovery. These are
  additive to the existing Farming Labs manifest and require no config flag.
- Identify the Farming Labs manifest by
  `$schema: "https://docs.farming-labs.dev/schema/agent-manifest.v1.json"` and
  `format: "farming-labs-agent-manifest.v1"`. Dynamic responses link the Draft 2020-12 schema with
  `rel="describedby"`. Do not confuse it with the separate, opt-in A2A Agent Card at
  `/.well-known/agent-card.json`.

## Agent discovery spec routes

The discovery spec exposed at `/.well-known/agent.json` and `/.well-known/agent` includes the following API route keys:

| Key                | Default route                           | Description                                                     |
| ------------------ | --------------------------------------- | --------------------------------------------------------------- |
| `config`           | `/api/docs?format=config`               | Machine-readable config map (`docs-config-map.v1`)              |
| `diagnostics`      | `/api/docs?format=diagnostics`          | Feature status and configuration issues (`docs-diagnostics.v1`) |
| `apiCatalog`       | `/.well-known/api-catalog`              | RFC 9727 JSON Linkset                                           |
| `agentSkillsIndex` | `/.well-known/agent-skills/index.json` | Hashed Agent Skills discovery index                             |

Agents that previously read only `config` should also check `diagnostics` to detect misconfigured or disabled features before attempting to use them.
The API catalog is intentionally absent when `staticExport: true` or `llmsTxt.apiCatalog: false`;
Agent Skills discovery remains available in both cases.

## Framework notes

- Next.js uses `withDocs()` and can expose page-level `.md`, `Accept: text/markdown`, and `Signature-Agent` markdown routes automatically.
- Farm.js serves docs and API-reference routes through `withDocs()`.
- TanStack Start, SvelteKit, Astro, and Nuxt use the shared docs API markdown mode through their framework-specific docs route setup.
- Do not switch frameworks unless the user explicitly asks to migrate.

## Follow-up pages

- Use [/docs/installation](/docs/installation) when the user is still wiring the framework into an app or has not created the docs route yet.
- Use [/docs/cli](/docs/cli) when they want scaffolding, upgrades, code block validation, sitemap generation, robots generation, search sync, or MCP commands instead of manual setup.
- Use [/docs/reference](/docs/reference) when they need the full typed `defineDocs()` surface or nested option details, including the `DocsDiagnostics` types and constants.
- Use [/docs/customization](/docs/customization) when the question moves from config into layout, sidebar, colors, or page-level polish.
- Use [/docs/themes](/docs/themes) when they are choosing a preset theme or building their own.
- Use [/docs/customization/components](/docs/customization/components) when the question is really about `components` or `theme.ui.components`.
- Use [/docs/customization/agent-primitive](/docs/customization/agent-primitive) when the user wants `.md` routes, hidden `<Agent>` content, or sibling `agent.md` overrides.
- Use [/docs/customization/mcp](/docs/customization/mcp) when they want machine-readable access through the built-in MCP server.
- Use [/docs/customization/llms-txt](/docs/customization/llms-txt) when they need crawler-friendly summaries for AI systems.
- Use [/docs/customization/sitemaps](/docs/customization/sitemaps) when they need `sitemap.xml`, `sitemap.md`, `/docs/sitemap.md`, static export files, or `lastmod` behavior.
- Use [/docs/customization/ai-chat](/docs/customization/ai-chat) when they are configuring Ask AI or retrieval-backed chat.
- Use [/docs/customization/page-actions](/docs/customization/page-actions) when they want Copy Markdown or Open in LLM actions.
- Use [/docs/token-efficiency](/docs/token-efficiency) when they care about retrieval quality, context size, or agent cost.

## Suggested exploration order

1. Confirm the runtime and config file path first.
2. Verify `entry`, `contentDir`, `nav`, and `theme` before discussing advanced features.
3. Move to `search`, `ai`, `mcp`, `pageActions`, `llmsTxt`, `sitemap`, or `robots` only after the base project shape is correct.
4. Use customization and theme pages once routing and content structure are stable.
5. Use markdown routes, sitemaps, `robots.txt`, `agent.compact`, MCP, and token-efficiency docs when the user is optimizing for agents or machine-readable access.

## Output style

- Prefer short, exact config examples.
- Preserve the user's framework if they already gave one.
- Do not invent config keys that are not part of `defineDocs()`.

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