Getting Started

MCP quick test

To verify the HTTP MCP route in this repo, use the Next example:

pnpm --dir examples/next dev

Then point your MCP client or inspector at http://127.0.0.1:3000/mcp or http://127.0.0.1:3000/.well-known/mcp.

Critical: theme CSS

Every setup must import the theme's CSS in the global stylesheet. Without it, docs pages will not be styled.

• Next.js: app/global.css → @import "@farming-labs/theme/<theme>/css"; (e.g. default, greentree, pixel-border).
• TanStack Start: src/styles/app.css (or your main global CSS file) → @import "@farming-labs/theme/<theme>/css";
• Farm.js: src/app/globals.css (or your main global CSS file) → @import "@farming-labs/theme/<theme>/css";
• SvelteKit: src/app.css → @import "@farming-labs/theme/<theme>/css";
• Astro: Import in the docs layout or page file: import "@farming-labs/theme/<theme>/css";
• Nuxt: nuxt.config.ts → css: ["@farming-labs/theme/<theme>/css"]

Use the same theme name in docs.config and in the CSS import.

Core config: defineDocs

All frameworks use a single config file (docs.config.ts or docs.config.tsx):

import { defineDocs } from "@farming-labs/docs";
import { fumadocs } from "@farming-labs/theme"; // or svelte-theme, astro-theme, nuxt-theme

export default defineDocs({
  entry: "docs",
  contentDir: "docs", // SvelteKit, Astro, Nuxt
  theme: fumadocs(),
  metadata: {
    titleTemplate: "%s – Docs",
    description: "My documentation site",
  },
});

• Next.js: docs.config.ts at project root; wrap Next config with withDocs() from @farming-labs/next/config. Content lives under app/docs/ (path derived from entry).
• TanStack Start: docs.config.ts or docs.config.tsx at project root; set contentDir and nav, create /api/docs, and load content from your docs/ directory via @farming-labs/tanstack-start/server.
• Farm.js: docs.config.ts at project root; set contentDir and nav, then wrap Farm's defineConfig() result with withDocs() from @farming-labs/farmjs/config. Farm owns development and production docs routing.
• SvelteKit: src/lib/docs.config.ts; routes under src/routes/docs/; set contentDir to the folder containing your markdown (e.g. docs).
• Astro: src/lib/docs.config.ts; pages under src/pages/<entry>/; set contentDir.
• Nuxt: docs.config.ts at project root; server/api/docs.ts and pages/docs/[...slug].vue; set contentDir and nav.

TanStack Start, Farm.js, SvelteKit, Astro, and Nuxt require contentDir (path to markdown files) and nav (sidebar title and base URL).

Optional generated pages

• API reference: Read references/api-reference.md when enabling local route scanning, a hosted OpenAPI document, or non-Next handler routes.
• Changelog: Read references/changelog.md when adding the generated Next.js release feed and dated entry pages.

Doc content and frontmatter

Docs live under the entry directory (e.g. docs/ or app/docs/). Each page is MDX or Markdown with frontmatter:

---
title: "Installation"
description: "Get up and running"
related:
  - /docs/configuration
  - /docs/customization/agent-primitive
icon: "rocket"
order: 1
---

# Installation

Content here.

Routing is file-based: docs/getting-started/page.mdx → /docs/getting-started. Use order in frontmatter to control sidebar order (numeric ordering).

Path aliases and defaults (CLI)

When running init and choosing Existing project, the CLI asks about path aliases (Next: @/, SvelteKit: $lib/, Nuxt: ~/ vs relative paths). If the user chooses "no alias", generated code uses relative paths to docs.config, and tsconfig may omit the paths block.

Optional defaults: Prompts that show a placeholder (entry path docs, theme name my-theme, project name my-docs, global CSS path) use that value as the default — the user can press Enter to accept without typing.

Static export

For fully static builds (e.g. Cloudflare Pages, no server), set staticExport: true in defineDocs(). This hides search and AI chat in the layout. Omit or do not deploy the docs API route so no server is required.

Common gotchas

1. Theme CSS missing — Docs look unstyled until the theme CSS is imported in the global stylesheet (or Nuxt css).
2. Wrong theme helper package — Use the framework theme helper for docs.config (e.g. @farming-labs/svelte-theme for SvelteKit), while theme CSS imports come from the shared @farming-labs/theme/<theme>/css path.
3. From scratch — Use init --template <next|tanstack-start|nuxt|sveltekit|astro> --name <project>; the CLI bootstraps a project with that name and runs install.
4. Existing project — Run init in the project root; the CLI detects the framework and scaffolds files.
5. Static hosting — Set staticExport: true; search and AI are then hidden.
6. API reference on non-Next frameworks — apiReference in docs.config is not enough by itself on TanStack Start, SvelteKit, Astro, or Nuxt; add the /{path} handler manually or let init --api-reference scaffold it, even when you use a remote specUrl.
7. Changelog generation today — The built-in generated changelog pages are currently wired in Next.js. Use the Next adapter if you want the turn-key /docs/changelogs flow.
8. TanStack Start in a monorepo — If the app and docs packages live in the same workspace, keep @farming-labs/docs, @farming-labs/theme, and @farming-labs/tanstack-start linked locally (for example workspace:*). This avoids Node 22 / Vercel loading raw adapter TypeScript from node_modules.

Resources

• Repo: github.com/farming-labs/docs
• Docs site: docs.farming-labs.dev (or the project's /docs route)
• Other skills in this repo: cli, creating-themes, ask-ai, page-actions, configuration under skills/farming-labs/.