@farming-labs/next

The Next.js App Router adapter for @farming-labs/docs.

It connects the shared docs configuration and theme to Next.js, compiles Markdown and MDX, generates the standard docs routes, and provides Next-native runtime helpers for documentation APIs, API references, MCP, and changelogs.

What this package does

• Wraps next.config.ts with the Farming Labs MDX and routing integration
• Generates missing docs layouts, API routes, MCP routes, and enabled feature routes
• Adds machine-readable Markdown, agent discovery, sitemap, and llms.txt rewrites
• Provides App Router layout, metadata, API-reference, and changelog helpers
• Preserves user-authored files and existing Next.js configuration

The shared config and CLI live in @farming-labs/docs. React UI, MDX components, providers, and theme CSS live in @farming-labs/theme.

Install

The CLI can add docs to an existing Next.js project:

npx @farming-labs/docs@latest init

For manual installation:

npm install @farming-labs/docs @farming-labs/next @farming-labs/theme

Minimal setup

Create docs.config.ts with defineDocs(), then wrap the Next.js config:

// next.config.ts
import { withDocs } from "@farming-labs/next/config";

export default withDocs();

Existing Next.js configuration can be passed directly:

export default withDocs({
  reactStrictMode: true,
});

Import the selected theme in your global stylesheet:

@import "tailwindcss";
@import "@farming-labs/theme/default/css";

Write documentation pages under app/docs/ or src/app/docs/. The CLI also adds the root RootProvider, generated docs layout, and server routes needed for a complete setup.

Extending MDX compilation

Set mdx in docs.config.ts and pass the live config to withDocs. Plugin module names and paths with JSON options work with both Webpack and Turbopack:

export default defineDocs({
  entry: "docs",
  mdx: {
    remarkPlugins: ["remark-directive", "./lib/remark-docs.mjs"],
    rehypePlugins: [["rehype-external-links", { target: "_blank" }]],
  },
});

import { withDocs } from "@farming-labs/next/config";
import docsConfig from "./docs.config";

export default withDocs({}, docsConfig);

Install the plugins in your application. Paths starting with ./ or ../ resolve from the application root. Extra plugins run after the built-in plugins in their respective phase; frontmatter, heading IDs, TOC, Markdown alternate links, and syntax highlighting remain enabled. Put callbacks and other non-JSON configuration inside a local plugin module.

For a migration with its own highlighter, set mdx.codeHighlighter to that plugin's module name or [module, options] tuple. This replaces only the default code-highlighting step, so code is highlighted once. The custom plugin owns its theme and code-block behavior. Omitting mdx keeps the existing defaults. These hooks do not configure Fumadocs collections or replace its source loader.

The third-argument withDocs(nextConfig, docsConfig, { mdx }) form is deprecated and still works. Setting mdx in both places throws.

The built-in highlighter uses Shiki's Oniguruma engine during compilation. A custom highlighter can import @farming-labs/next/mdx-plugins/rehype-code to keep that default while configuring themes and transformers. Passing engine: "js" explicitly selects Shiki's JavaScript engine.

Page metadata transport

Production builds send title, description, reading time, dates, and structured data with each compatible Markdown/MDX page. The shared layout keeps navigation and theme settings. This changes the data boundary without changing the rendered page markup or the theme API.

Automatic selection applies to ordinary file routes using the standard generated layout and MDX provider. Customized layouts, MDX providers, compiler extensions, components.wrapper, development, localized layouts, multiple docs roots, custom content directories, Next.js basePath, nested layouts/templates, dynamic/group/parallel routes, and authored MDX exports keep the existing site-wide metadata path. Code fences containing exports remain eligible. Older installed core or theme packages without the boundary support also keep the existing path.

To retain site-wide metadata explicitly:

export default withDocs({}, undefined, { pageMetadata: "site" });

The default is pageMetadata: "auto". Both transports use the same metadata builder and page component. Custom compiler extensions retain the existing transport. The boundary subpaths are internal compiler integration points, not application component APIs.

Main entrypoints

Requirements

• Next.js 16 or newer
• React and React DOM 19.2 or newer
• @farming-labs/docs 0.2.121 or newer and @farming-labs/theme

Learn more

• Documentation
• Next.js example
• GitHub repository

License

MIT