farming-labs-docs（农业实验室文档）

@farming-labs/docs — Getting Started

Always consult the project docs (and /docs routes when available) for the latest API and examples.

@farming-labs/docs is a modern, flexible MDX-based documentation framework. Write markdown, get a polished docs site. Supported frameworks: Next.js, SvelteKit, Astro, Nuxt.

Quick reference

CLI

CLI flags

Packages by framework

Themes (all frameworks)

Seven built-in themes: fumadocs, darksharp, pixel-border, colorful, greentree, darkbold, shiny. Theme name in config must match the theme’s CSS import path (e.g. greentree → @farming-labs/theme/greentree/css for Next).

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).
• SvelteKit: src/app.css → @import "@farming-labs/svelte-theme/<theme>/css";
• Astro: Import in the docs layout or page file: import "@farming-labs/astro-theme/<theme>/css";
• Nuxt: nuxt.config.ts → css: ["@farming-labs/nuxt-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.ts):

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
  // staticExport: true, // optional: for full static builds (Cloudflare Pages); hides search & AI
  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.
• SvelteKit: src/lib/docs.config.ts; routes under src/routes/docs/.
• Astro: src/lib/docs.config.ts; pages under src/pages/<entry>/.
• Nuxt: docs.config.ts at project root; server/api/docs.ts and pages/docs/[...slug].vue.

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"
icon: "rocket"
---

# Installation

Content here.

Routing is file-based: docs/getting-started/page.mdx → /docs/getting-started.

Path aliases (CLI)

When running init, the CLI may ask about path aliases:

• Next.js: @/ (e.g. @/docs.config) vs relative paths.
• SvelteKit: $lib/ vs relative.
• Nuxt: ~/ vs relative.

If the user chooses “no alias”, generated code uses relative paths to docs.config (e.g. ../../docs.config), and tsconfig may omit the paths block.

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 package — Use the theme package for the same framework (e.g. @farming-labs/svelte-theme for SvelteKit, not @farming-labs/theme).
3. From scratch — Use --template with --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 — For full static builds (e.g. Cloudflare Pages), set staticExport: true in defineDocs(); search and AI are then hidden and no server is required.

Resources

• Repo: farming-labs/docs
• Docs site: Check the project’s /docs (e.g. installation, CLI, configuration).
• Examples: examples/next, examples/nuxt, examples/sveltekit, examples/astro in the repo.