# Introduction
URL: /docs
LLM index: /llms.txt
Description: An AI-native documentation framework that just works
Related: /docs/installation, /docs/guides, /docs/configuration, /docs/customization/agent-primitive, /docs/customization/llms-txt, /docs/customization/sitemaps, /docs/customization/mcp, /docs/cli

# @farming-labs/docs

An AI-native documentation framework built on top of <HoverLink href="https://fumadocs.dev" title="Fumadocs" description="The MDX docs toolkit and UI foundation that powers the core reading experience behind @farming-labs/docs." linkLabel="Visit Fumadocs" external>Fumadocs</HoverLink> and other preset providers. One config file, zero boilerplate, with docs that are ready for humans, IDEs, and agents out of the box.

You are reading the machine-readable entry page for `@farming-labs/docs`.

Before implementing from this docs site, fetch `/.well-known/agent.json` from the same origin. If
that is unavailable, fall back to `/.well-known/agent`. Treat that JSON as the source of truth for
the docs entry path, markdown route pattern, search endpoint, MCP endpoint, `llms.txt` routes,
OpenAPI schema route, `sitemap.xml` / `sitemap.md` routes, `robots.txt` route, `AGENTS.md` route, `skill.md` route,
skills install command, JSON-LD structured data, locale handling, `Signature-Agent` support, and
feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent`.
2. Read `spec.skills.route` or `spec.skills.wellKnown` when a concise site skill is useful.
3. Use `spec.markdown.pagePattern`, `spec.markdown.acceptHeader`, or `spec.markdown.signatureAgentHeader` to read the exact docs pages you need as markdown.
4. Use `spec.search.endpoint` when you need to find the right page before reading it.
5. Use `spec.openapi.url` before scraping API reference pages when `spec.openapi.enabled` is true.
6. Use `spec.sitemap.markdown.route` for the semantic page map and `spec.sitemap.xml.route` for canonical URL freshness when sitemap is enabled.
7. Fetch `spec.robots.route` when you need to confirm crawler and AI-agent access policy for the public docs surface.
8. Use `spec.mcp.wellKnownEndpoint` or `spec.mcp.publicEndpoint` when available, otherwise `spec.mcp.endpoint`, when MCP is enabled and the environment supports MCP.
9. If `spec.feedback.enabled` is true, fetch `spec.feedback.schema` before submitting to `spec.feedback.submit`.

Do not scrape the HTML page when markdown, search, OpenAPI, sitemap, robots, MCP, or `llms.txt`
routes are available in the spec.

## Why @farming-labs/docs?

- **Zero boilerplate** — No layout files, no `[[...slug]]` wrappers except for fully fledged functionality like AI, Search and metadata to work. Just write Markdown or MDX.
- **One config** — Everything in `docs.config.ts`: theme, colors, typography, icons, components, metadata.
- **Token efficient** — Your entire docs framework surface is a single config file (~15 lines). AI tools like Cursor, Copilot, and Claude spend less time reading framework plumbing and more time working with your actual content. Built-in JSON-LD structured data, [llms.txt](/docs/customization/llms-txt), [sitemaps](/docs/customization/sitemaps), generated `robots.txt`, and `docs agent compact` keep the machine-readable layer lean too. [Learn more →](/docs/token-efficiency)
- **Multiple frameworks** — First-class support for Next.js, TanStack Start, SvelteKit, Astro, and Nuxt that just works.
- **11 themes** — Default, Darksharp, Pixel Border, Colorful, Shiny, Ledger, DarkBold, GreenTree, Concrete, Command Grid, and Hardline — or build your own with [`createTheme()`](/docs/themes/creating-themes).
- **Built-in search** — Zero-config simple search by default, or upgrade to Typesense, Algolia, or a custom adapter.
- **CLI scaffolding** — `npx @farming-labs/docs init` first asks whether you're on an **existing project** or **starting fresh**; then it detects your framework, lets you pick a theme (or create your own), can scaffold locale folders for i18n, and generates config, routes, and sample pages. Use `--template` with `--name` to bootstrap a new project without prompts.

## Looking Ahead: Cloud

[Cloud](/cloud) is the infrastructure layer we are building around `@farming-labs/docs`.

**You ship the code and we write the docs for you.**

The open runtime stays yours. Cloud adds the managed layer around it for teams that want stronger
search, retrieval, analytics, review workflows, and agent-ready docs operations without giving up
Git as the source of truth.

[Join the waitlist to be an early user →](/cloud#waitlist)

## other docs frameworks?

<Callout type="info" title="Complementary, not a replacement">
We are not trying to replace Fumadocs — we aim to be **complementary**. @farming-labs/docs builds on <HoverLink href="https://fumadocs.dev" title="Fumadocs" description="A docs-focused toolkit for MDX content, layouts, search integrations, and polished documentation UI." linkLabel="Open Fumadocs" external>Fumadocs</HoverLink> (and other providers) to offer a single config, multi-framework support, and optional themes and tooling, so you can use Fumadocs with less boilerplate and across Next.js, TanStack Start, SvelteKit, Astro, and Nuxt.
</Callout>

If you're choosing between documentation tools, here’s when @farming-labs/docs is a good fit:

- **vs. Fumadocs alone** — You get the same UI and MDX experience, but with a single `docs.config` and first-class support for TanStack Start, SvelteKit, Astro, and Nuxt — not just Next.js. One config model and CLI so you don’t wire layouts, themes, and search by hand.
- **vs. Docusaurus / VitePress** — You keep full control inside your existing app (Next, TanStack Start, SvelteKit, Astro, Nuxt) instead of a separate docs site. No separate framework or build; your docs live in the same repo and stack, with one config file and optional built-in AI chat and search.
- **vs. Mintlify / ReadMe / hosted docs** — You own the code and hosting. No vendor lock-in or per-seat pricing; you can deploy to Vercel, Cloudflare Pages, or anywhere. Built-in [llms.txt](/docs/customization/llms-txt), [sitemaps](/docs/customization/sitemaps), generated `robots.txt`, and [AI chat](/docs/customization/ai-chat) give you AI-friendly docs without a third-party docs platform.
- **vs. hand-rolled MDX** — No need to build layouts, catch-all routes, search, or theming yourself. The CLI scaffolds everything; you spend time on content and optional customization (themes, colors, sidebar, page actions) instead of framework plumbing.

In short: use @farming-labs/docs when you want an **AI-native docs runtime**, **one config**, **multiple frameworks**, and minimal boilerplate — without leaving your current stack or adopting a separate docs-only framework.

## Customize themes and share them

You can [create your own theme](/docs/themes/creating-themes) and distribute it to others — as an npm package, a shared preset, or a CSS file. Themes control layout, colors, typography, and components; once built, anyone can plug them in via config. See [Themes](/docs/themes) for built-in presets and [Creating themes](/docs/themes/creating-themes) for the full API.

## Built-in docs UI — enable and customize from config

Modern docs features are built in; you turn them on in [configuration](/docs/configuration) instead of wiring them yourself. Each element can be customized — layout, behavior, and appearance — via the same config and theme options. See [Customization](/docs/customization) for the full overview.

- **[Ask AI](/docs/customization/ai-chat)** — RAG-powered chat, multiple models and providers, floating or sidebar mode. [Customize](/docs/customization/ai-chat) labels, suggested questions, model list, and UI mode.
- **Search** — Built-in simple search works out of the box, and you can switch to Typesense, Algolia, or a custom adapter from [configuration](/docs/configuration).
- **[Page actions](/docs/customization/page-actions)** — Copy Markdown, open in ChatGPT/other tools. [Customize](/docs/customization/page-actions) which actions appear and their options.
- **[Sidebar](/docs/customization/sidebar)** — Collapsible, flat or nested, banner, footer. [Customize](/docs/customization/sidebar) structure, style, and content (banner, footer, nav title).
- **[Components](/docs/customization/components)** — Built-in MDX components like `Callout`, `Tabs`, and `HoverLink`, plus your own custom React components.
- **[llms.txt](/docs/customization/llms-txt)** — LLM-friendly index whose page links point directly to markdown routes. Options described in the [llms.txt docs](/docs/customization/llms-txt).
- **[Sitemaps](/docs/customization/sitemaps)** — XML and Markdown maps of canonical docs URLs, descriptions, related pages, and freshness metadata. Runtime routes are enabled by default.
- **Robots.txt** — Runtime agent-friendly crawl policy at `/robots.txt` when no static file already exists; use `docs robots generate` for static export or committed policies.

Theme-level customization (colors, typography, components) is covered in [Configuration](/docs/configuration) and [Customization](/docs/customization) (including [Colors](/docs/customization/colors) and [Typography](/docs/customization/typography)). No custom components or routes required — enable and tweak what you need in `docs.config`.

## Packages

| Package                      | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `@farming-labs/docs`         | Core types, `defineDocs()`, `createTheme()`, `extendTheme()`                         |
| `@farming-labs/theme`        | Next.js theme presets, layout components, CSS presets                                |
| `@farming-labs/next`         | Next.js adapter — `withDocs()`, MDX processing, search API                           |
| `@farming-labs/tanstack-start` | TanStack Start adapter — docs page renderer, MDX processing, search API, server loader |
| `@farming-labs/svelte`       | SvelteKit adapter — server-side docs loader, markdown processing                     |
| `@farming-labs/svelte-theme` | SvelteKit theme presets, DocsLayout, DocsContent components                          |
| `@farming-labs/astro`        | Astro adapter — server-side docs loader, markdown processing                         |
| `@farming-labs/astro-theme`  | Astro theme presets, DocsLayout, DocsContent components                              |
| `@farming-labs/nuxt`         | Nuxt 3 adapter — `defineDocsHandler()`, server-side docs loader, markdown processing |
| `@farming-labs/nuxt-theme`   | Nuxt theme presets, DocsLayout, DocsContent components                               |

## Quick Start

The fastest way to get started is with the CLI:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash title="terminal"
    npx @farming-labs/docs init
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash title="terminal"
    pnpm dlx @farming-labs/docs init
    ```
  </Tab>
  <Tab value="yarn">
    ```bash title="terminal"
    yarn dlx @farming-labs/docs init
    ```
  </Tab>
  <Tab value="bun">
    ```bash title="terminal"
    bunx @farming-labs/docs init
    ```
  </Tab>
</Tabs>

The CLI first asks **existing project or fresh?** — then (for existing) auto-detects your framework, lets you pick a theme or **create your own**, can scaffold locale folders and `i18n` config, and generates config, routes, CSS, and sample pages. Prompts with a default (e.g. entry path `docs`) accept **Enter** to skip typing. See the [CLI reference](/docs/cli) for the full init flow, or set up manually with the [Installation guide](/docs/installation).

## Next Steps

- [Guides](/docs/guides) — Long-form playbooks, starting with writing agent-friendly docs
- [Token Efficiency](/docs/token-efficiency) — Why this is the most AI-friendly docs framework
- [Cloud](/cloud) — Where the managed infrastructure layer for humans and agents is heading
- [Configuration](/docs/configuration) — Customize your theme, colors, typography, sidebar, and more
- [Themes](/docs/themes) — Browse available themes and learn how to create your own
- [Customization](/docs/customization) — Colors, typography, sidebar, AI chat, page actions
- [Ask AI](/docs/customization/ai-chat) — Add RAG-powered AI chat to your docs
- [API Reference](/docs/reference) — Complete reference for every config option
- [Contributing](/docs/contributing) — How to report issues, suggest features, and submit pull requests