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

# 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`
  - `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`, and `get_config_schema`
  - `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 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.

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

Agents that previously read only `config` should also check `diagnostics` to detect misconfigured or disabled features before attempting to use them.

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