---
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`
   - `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.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`.
- 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. Configured retrieval also fails at `searchTimeoutMs`, which defaults to 30 seconds
  per task. 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.

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