Why I Built @farming-labs/docs for the AI Era

There are already a lot of documentation tools.

So when I started building docs.farming-labs.dev, the goal was not to make "yet another docs site." The goal was to build a docs framework that feels small, practical, and easy to adapt to real products.

The bigger idea is that docs are no longer only a website. They are also product context. They are what a teammate reads, what an implementation agent fetches, what search indexes, what an IDE assistant uses to make changes safely, and what a support workflow can point people toward.

Why I Built It

Most docs tools push you into one of two extremes:

• polished, but too rigid
• flexible, but full of wiring and boilerplate

I wanted something in the middle: MDX-based, good-looking by default, but still simple enough to understand quickly. Docs should not feel like a second app you have to maintain just to publish a page.

That is why the project keeps the real setup surface centered around one config file and supports multiple frameworks instead of trapping you inside one stack. The docs should be easy to start, easy to theme, easy to index, and easy for agents to consume directly.

Why It Fits The AI Era

Today docs are not only read by humans. They are also read by AI tools, agents, copilots, search systems, and retrieval pipelines.

That changes the design goal.

In this AI era, boilerplate is not just ugly, it is expensive. Every extra wrapper or config layer becomes more context for a model to read before it can reach the actual documentation.

So one of the main ideas behind docs.farming-labs.dev is simple:

keep the framework surface small so humans and AI can understand the project faster.

That is why the project leans on:

• one docs.config.ts as the main control surface
• minimal generated files
• built-in llms.txt support
• page-level Markdown routes and content negotiation for tailored agent responses
• built-in MCP server support
• hidden Agent blocks and page-local agent.md overrides
• built-in AI chat instead of bolted-on integrations
• agent feedback endpoints so automated workflows can report useful context back

AI-Native Means More Than Adding A Chatbot

It is easy to put a chat box on top of documentation and call the result AI-native. That is useful, but it does not solve the harder problem: can an agent discover the docs, select the correct version and framework, retrieve only the evidence it needs, follow an executable task, cite its sources, and report when the documentation fails?

Making the same human page available as raw Markdown is a good start, but that alone is not AI-native either. A visually rich page may contain navigation hints, screenshots, repeated explanation, or presentation copy that is helpful to a person but wastes an agent's context. An agent may instead need exact file paths, commands, version boundaries, side effects, verification steps, and recovery instructions that would make the human page harder to read.

I use AI-native to describe the architecture, not one feature. In @farming-labs/docs, the machine-readable layer starts with the same MDX source as the human site and is carried through the whole system:

1. Pages can contain shared content plus explicit Agent, Human, and Audience blocks.
2. Human pages and search use the human projection; Markdown routes, Ask AI, MCP, llms-full.txt, and static Agent Bundles use the agent projection.
3. Page frontmatter can describe the task, expected outcome, prerequisites, files, commands, side effects, verification, rollback, failure modes, framework, package version, and token budget.
4. The same structured contract becomes useful Markdown, search context, MCP task tools, and Schema.org HowTo data.
5. Agent discovery, evaluation, feedback, and content-change tools make the docs observable after publication.

That means the AI layer is not a second, stale copy of the documentation. It is a different projection of the source the team already reviews.

One Source, Dynamically Tailored For The Reader

A page can express the difference directly in MDX:

# Configure Cloud

Shared explanation for everyone.

<Human>
  Open Project Settings, choose API Keys, and copy the key into your local
  environment.
</Human>

<Agent>
  Read docs.config.ts, preserve unrelated settings, store the key only in
  DOCS_CLOUD_API_KEY, run docs cloud check, and report any failing scope without
  printing the secret.
</Agent>

A normal browser receives the human-facing site. Machine-readable routes receive the shared content plus the agent instructions and leave out the human-only presentation. In Next.js, the canonical page URL can dynamically return that tailored Markdown when the request sends Signature-Agent or an unambiguous Accept: text/markdown header. Every supported adapter also exposes exact .md routes, while Ask AI, MCP, llms-full.txt, search with an agent audience, and static Agent Bundles reuse the same agent projection.

This is more than putting Markdown beside a website. The website behaves as a content system that can serve the representation appropriate to its consumer. Humans can get visual guidance, interactive components, and product context; agents can get dense, task-oriented instructions with stable metadata and less noise.

Audience projection is not authentication. Agent-specific content remains public documentation and must never contain secrets. Its job is to tailor useful context, not to create a security boundary.

Why Choose It Over A Conventional Docs Stack?

There are excellent existing documentation tools, and not every project should move. The reason to choose @farming-labs/docs is not that every alternative is bad. It is that this project combines a set of priorities that usually require separate tools and custom glue.

If you care about	What @farming-labs/docs gives you
Staying in your framework	Adapters for Next.js, TanStack Start, SvelteKit, Astro, and Nuxt with a consistent MDX and configuration model
Keeping the setup understandable	One docs.config.ts control surface for the theme, navigation, search, AI, feedback, metadata, agent interfaces, and Cloud settings
Serving humans and agents from one source	Dynamically tailored audience projections, page-level agent.md, content-negotiated Markdown, MCP, llms.txt, Agent Skills, and discovery manifests
Controlling context cost	Per-page token budgets, agent compaction, compact and full LLM indexes, bounded MCP context, and retrieval evaluations
Owning the visual identity	Eleven built-in themes, createTheme, extendTheme, design tokens, component defaults, custom CSS, and publishable theme packages
Measuring quality before shipping	Reader and agent doctor audits, review scoring, command checks, golden retrieval tasks, citation checks, and code-block validation
Avoiding platform lock-in	An open-source, repository-first framework with an optional hosted Cloud layer rather than a required hosted editor

For a conventional human-only docs site, several of these capabilities may not matter. But once documentation becomes input to coding agents, internal support, retrieval pipelines, or customer-facing AI, adding every interface separately creates more code, more drift, and more places to debug.

Token Efficiency Is A Product Constraint

Token efficiency is not only about making files short. The goal is to spend the available context on evidence that helps complete the task.

The framework attacks that problem at several levels:

• the main framework surface stays concentrated in docs.config.ts, so an agent does not have to reverse-engineer a large provider and routing tree before it can edit the docs
• <Human> content can keep visual explanation and presentation details out of agent context, while <Agent> can add precise machine-only instructions
• a sibling agent.md can replace a long visual page with a focused operational version without changing what readers see
• agent.tokenBudget sets a page-level output target, and docs agent compact can generate or refresh the smaller representation
• compact llms.txt files act as maps to relevant Markdown instead of dumping the entire site into every prompt; llms-full.txt remains available when a complete corpus is actually appropriate
• MCP get_context and content hydration accept hard token budgets, returning selected sections and source anchors instead of an unbounded page dump
• Ask AI controls how many retrieved results become model context
• golden evaluations can check retrieval rank, citations, relevant and forbidden sources, framework and version scope, executable examples, and useful-byte ratio within a configured context budget

That is the difference between saying docs are "optimized for AI" and giving a team tools to measure whether the right information survives retrieval and compression.

Theme Customization Is Not Limited To A Brand Color

Documentation is part of the product. It should be able to look like the product instead of a hosted template with a logo swapped in.

The project includes eleven starting points: fumadocs, darksharp, pixel-border, colorful, greentree, darkbold, shiny, ledger, concrete, command-grid, and hardline. A team can use one directly, extend one, cherry-pick defaults from several themes, or create a new system from scratch.

The theme contract can control:

• the full color system for light and dark modes
• font families, sizes, weights, line heights, and letter spacing
• content, sidebar, and table-of-contents widths
• table-of-contents depth and visibility
• header height and sticky behavior
• sidebar style, backgrounds, and borders
• code themes, line numbers, and copy controls
• cards, radii, callouts, tabs, hover links, and other component defaults
• custom icons and MDX component replacements

When configuration tokens are not enough, the theme can ship CSS for pixel-level control. When a team wants the same docs identity across products, it can publish the theme as a normal npm package, version it, and roll improvements out without copying styles between repositories.

That makes the theming model useful for both ends of the spectrum: start with a polished preset in minutes, or make the documentation feel like a native part of an existing design system.

Search And Ask AI Share The Documentation Model

Search can start with the zero-configuration section index and later move to Typesense, Algolia, MCP, or a custom adapter. Human and agent requests receive the appropriate audience projection, and structured results can explain matched terms, filters, provenance, and ranking decisions when an integration needs to inspect retrieval.

Ask AI uses that retrieval layer rather than treating the whole site as one giant prompt. It can appear inside search or as a floating panel, modal, popover, or full-screen experience. It supports suggested questions, response feedback, multiple selectable models, multiple OpenAI-compatible providers, custom prompts, and MCP-backed retrieval.

The practical benefit is that a team can begin with a small default and keep control as its requirements grow. It does not have to replace the docs framework just because it needs a different model, search provider, retrieval path, or chat interface.

It Is Still A Documentation Framework For People

AI support should not make the reader experience worse. The same project includes the normal product-docs work: responsive navigation, reusable MDX components, page actions, code-copy hooks, human feedback, generated API reference, changelog pages, reading time, breadcrumbs, SEO metadata, JSON-LD, Open Graph images, and light and dark modes.

The human experience and the agent experience are separate projections, but they are not separate products.

When It Is The Right Choice — And When It Is Not

I think @farming-labs/docs is a strong fit when:

• your docs should live beside the code and remain reviewable in Git
• you want a real custom design rather than a lightly branded hosted template
• your team uses more than one supported web framework
• coding agents, support agents, MCP clients, or retrieval systems consume the documentation
• you want to measure agent readiness and token usage instead of relying on a chatbot demo
• you want an open-source runtime with optional managed infrastructure

It may not be the best fit when you want a completely no-code hosted editor, do not want docs in a repository, or only need a small static brochure with no custom runtime or agent workflows. Those are valid requirements. I would rather be clear about the tradeoff than claim one docs tool is right for everyone.

Getting Started And Working With It

Getting started should feel boring:

npx @farming-labs/docs init

The CLI detects the framework, lets you choose a theme, scaffolds the minimal files, installs dependencies, and gets the dev server running. If you are starting fresh, it can scaffold a new project too.

It can also help with the parts that normally make docs annoying later: i18n folders, generated API reference setup, framework route files, theme CSS, and the minimal config needed to keep everything readable.

The day-to-day workflow stays close to content:

• write Markdown or MDX
• keep docs in a docs directory
• control the site from docs.config.ts

import { defineDocs } from '@farming-labs/docs'
import { fumadocs } from '@farming-labs/theme'

export default defineDocs({
  entry: 'docs',
  theme: fumadocs(),
  nav: { title: 'My Docs', url: '/docs' },
  metadata: {
    titleTemplate: '%s - Docs',
    description: 'My documentation site',
  },
})

That is the kind of ergonomics I wanted: small enough to read in one glance, but strong enough to run a real docs site.

For agent workflows, the same package can also run the built-in MCP server locally:

npx @farming-labs/docs mcp

That means a local assistant or IDE agent can query the docs through tools like list_pages, get_navigation, search_docs, and read_page instead of scraping the rendered website.

Why Customization Matters

I did not want "easy to use" to mean "hard to customize."

The project is designed so the important parts are open:

• themes, colors, typography
• sidebar behavior and components
• page actions
• AI chat
• llms.txt
• OG images
• search providers
• generated API reference
• changelog pages
• human and agent feedback

Creating a theme is intentionally simple:

import { createTheme } from '@farming-labs/docs'

export const myTheme = createTheme({
  name: 'my-theme',
  ui: {
    colors: {
      primary: '#e11d48',
      background: '#09090b',
      muted: '#71717a',
      border: '#27272a',
    },
  },
})

And if you want to start from an existing preset instead of from zero:

import { extendTheme } from '@farming-labs/docs'
import { fumadocs } from '@farming-labs/theme'

export const myTheme = extendTheme(fumadocs(), {
  name: 'my-fumadocs-variant',
  ui: {
    colors: { primary: '#22c55e', background: '#0c0c0c' },
    sidebar: { style: 'bordered' },
  },
})

That part matters because good themes should be reusable. A team can publish a theme as an npm package, reuse it across projects, and effectively build its own theme registry or shared preset system instead of copying styles from app to app.

That sharing model was important to me. A good docs theme should not be trapped inside one repo. It should be something you can install, version, improve, and roll out across multiple products the same way you would handle any other shared design system package.

The built-in themes also give teams somewhere useful to start. You can use presets like fumadocs, darksharp, pixel-border, colorful, greentree, darkbold, shiny, ledger, concrete, command-grid, or hardline, then extend only the pieces you care about. The goal is not to make every docs site look the same. The goal is to make custom docs cheaper to build and easier to share.

What Changed Since The First Version

The project has grown into more than a docs renderer. It now treats documentation as something that should be authored once but published through several useful interfaces.

The human-facing side includes generated API reference, changelog pages, reusable themes, search adapters, page actions, and MDX components. The machine-facing side now includes Agent Skills discovery, Markdown content negotiation, sitemaps, generated robots.txt, an RFC 9727 API catalog, MCP, and a complete agent discovery manifest.

Some of the most useful recent additions are operational tools rather than UI features:

• docs doctor --agent measures whether agents can discover, retrieve, and use the docs
• docs doctor --site audits navigation, descriptions, structure, trust signals, and reader feedback
• docs agent compact generates smaller page-level agent.md files without changing the human page
• docs agent export --public creates a complete static Agent Bundle with a deterministic SHA-256 manifest
• MCP content-change tools let clients poll for document changes and hydrate only the sections that fit their token budget
• conformance work keeps the important MCP and agent surfaces consistent across Next.js, TanStack Start, SvelteKit, Astro, and Nuxt

There are also feedback surfaces that make docs useful outside the page itself. Readers can copy Markdown, open a page in an LLM, or leave feedback. Agents can submit structured feedback through machine-readable endpoints.

That is the part I care about: docs should not be a static brochure. They should be a working interface between the product, the reader, the team, and the tools around them.

From An Open-Source Framework To Docs Cloud

The framework remains open source. Your repository is the source of truth, and your application still owns its docs runtime.

Docs Cloud is the hosted infrastructure around that framework. It adds managed project workflows without asking a team to hand over ownership of its content:

• connect and synchronize repository-backed docs projects
• validate the Cloud contract before a deployment
• create hosted preview deployments
• collect privacy-conscious analytics for both human and agent traffic
• power managed retrieval and Ask AI
• detect knowledge drift and support reviewable publishing workflows

Docs Cloud is currently in private beta. A small group of teams is already using the infrastructure for real documentation workflows, and it is serving those workflows well. That matters to me because the system is no longer being shaped only by imagined use cases. Real repositories, permissions, deployments, CORS rules, retrieval needs, and review habits are forcing the product to become more practical.

We Use The Same Infrastructure Every Day

Farming Labs is also a daily user of @farming-labs/docs and Docs Cloud. The docs for the project run on the framework, and we use the Cloud infrastructure while building and maintaining them.

That dogfooding loop has been one of the best product decisions we made. When an agent cannot find the right page, a Cloud check misses a configuration problem, a preview is awkward to review, or analytics cannot explain how the docs are being used, we encounter the problem ourselves. The fix goes back into the same product that private-beta users receive.

I do not want the public docs site to be a polished demo running on a separate, special-case stack. I want it to prove that the open-source framework and the hosted infrastructure can handle the ordinary work of shipping, measuring, and improving documentation day after day.

AI, Agentic Features, And OG Support

The AI features are there because they belong there.

AI chat can be enabled with a very small config surface:

ai: {
  enabled: true,
  model: "gpt-4o-mini",
}

But it goes beyond a single model call. The chat can live inside search or as a floating UI, can use one model or multiple selectable models, and can route different models through different OpenAI-compatible providers.

Around that, there are other AI-friendly features too:

• llms.txt and llms-full.txt output
• page actions like "Copy Markdown" and "Open in..."
• token-efficient config that agents can read quickly
• machine-readable .md routes like /docs/quickstart.md
• Accept: text/markdown and Signature-Agent support on normal docs URLs
• hidden Agent blocks for machine-only instructions
• agent.md files when a page needs a focused agent-specific version
• an agent spec route at /api/docs/agent/spec
• standards-based Agent Skills and API discovery
• agent feedback schema and submit routes
• built-in MCP support through /api/docs/mcp and npx @farming-labs/docs mcp
• static Agent Bundles for deployments that do not have a dynamic docs runtime
• installable Agent Skills for setup, CLI usage, theme creation, Ask AI, page actions, and configuration

That combination matters more than any one feature by itself. I wanted the docs to work well for people reading normally, for people sharing pages into AI tools, and for systems that need a structured way to consume the content.

The important detail is that the agentic layer is not just "add chat to the docs." It is a whole set of surfaces:

• humans get polished pages
• search gets normalized chunks
• LLMs get llms.txt
• agents get markdown routes, Agent blocks, agent.md, MCP tools, and an agent spec
• teams get feedback endpoints so automation can report what worked or failed

That makes the docs easier to use in Cursor, Copilot-style workflows, local MCP clients, internal support tools, and retrieval systems without forcing every team to invent the same glue code again.

And docs also need strong OG image support. Shared docs links should look good, not broken or generic.

That is why the framework supports both:

• dynamic OG images through an endpoint like /api/og
• static per-page OG images from frontmatter when a page needs a custom image

That mix matters. Most docs sites need a clean default OG system for the whole site, but they also need the option to override important pages with a better static image.

For me, that is one of those details that makes docs feel more complete. A docs page is not only something people read on-site. It is something they paste into Slack, X, Discord, and issue threads. Better OG support makes the docs feel more intentional everywhere else too.

Why Multi-Framework Support Still Matters

I also did not want this to only make sense for one ecosystem.

Teams already have strong preferences around Next.js, TanStack Start, SvelteKit, Astro, and Nuxt. Good docs infrastructure should meet them where they already are instead of asking them to switch frameworks just to get a better docs experience.

So part of the idea here was to keep the authoring model and config model consistent, while adapting the integration details to each framework.

Final Thought

I created docs.farming-labs.dev because I think documentation is becoming more central, not less.

In the AI era, docs are part of onboarding, search, retrieval, and product experience. So I wanted a docs framework that stays simple, looks polished, feels customizable, and works well for both humans and AI.

If you want to explore the open-source framework, the easiest way to start is still:

npx @farming-labs/docs init

You can also read the documentation, inspect the source on GitHub, or look at the Docs Cloud direction.

If your team wants help trying it, migrating an existing docs site, or joining the private beta, email me at kinfetare83@gmail.com. I am especially interested in hearing where the framework or Cloud gets in the way of a real documentation workflow.