@farming-labs/docs — Configuration
All configuration lives in a single docs.config.ts (or docs.config.tsx) file. Use this skill when editing or explaining config options.
Full docs: Configuration, API Reference.
Config file location by framework
| Framework |
Config path |
| Next.js |
Project root: docs.config.ts |
| SvelteKit |
src/lib/docs.config.ts |
| Astro |
src/lib/docs.config.ts |
| Nuxt |
Project root: docs.config.ts |
SvelteKit, Astro, and Nuxt require contentDir (path to markdown files) and nav (sidebar title and base URL) in addition to entry and theme.
Main config options
| Option |
Type |
Default |
Description |
entry |
string |
"docs" |
URL path prefix for docs (e.g. "docs" → /docs) |
contentDir |
string |
same as entry |
Path to content files (SvelteKit, Astro, Nuxt) |
staticExport |
boolean |
false |
Set true for full static builds; hides search and AI |
theme |
DocsTheme |
— |
Theme from a theme factory (e.g. fumadocs(), pixelBorder()) |
nav |
{ title, url } |
— |
Sidebar title and base URL (required for SvelteKit, Astro, Nuxt) |
github |
string | GithubConfig |
— |
GitHub repo for "Edit on GitHub" and {githubUrl} in page actions |
themeToggle |
boolean | ThemeToggleConfig |
true |
Light/dark mode toggle |
breadcrumb |
boolean | BreadcrumbConfig |
true |
Breadcrumb navigation |
sidebar |
boolean | SidebarConfig |
true |
Sidebar visibility and style |
icons |
Record<string, Component> |
— |
Icon registry for frontmatter icon fields |
components |
Record<string, Component> |
— |
Custom MDX components (e.g. Callout) |
onCopyClick |
(data: CodeBlockCopyData) => void |
— |
Callback when user copies a code block (title, content, url, language) |
pageActions |
PageActionsConfig |
— |
Copy Markdown, Open in LLM (see page-actions skill) |
ai |
AIConfig |
— |
RAG-powered AI chat (see ask-ai skill) |
metadata |
DocsMetadata |
— |
SEO: titleTemplate, description, etc. |
og |
OGConfig |
— |
Dynamic Open Graph images |
Static export
For fully static builds (e.g. Cloudflare Pages, no server):
export default defineDocs({
entry: "docs",
staticExport: true,
theme: fumadocs(),
});
- Search (Cmd+K) and AI chat are hidden in the layout.
- Next.js: with
output: "export" in next.config, the /api/docs route is not generated.
- Do not deploy the docs API route when using static export.
GitHub (Edit on GitHub and openDocs)
github: {
url: "https://github.com/owner/repo",
directory: "website", // optional: subdirectory where docs content lives
}
Enables "Edit on GitHub" links and allows {githubUrl} in pageActions.openDocs.providers.
Theme toggle
themeToggle: {
enabled: true, // show toggle (default)
default: "light" | "dark" | "system",
}
Set enabled: false to hide the toggle or force a single mode.
Sidebar and breadcrumb
- sidebar:
true (default) or SidebarConfig (style, banner, footer, etc.). See customization docs for banner/footer content.
- breadcrumb:
true (default) or BreadcrumbConfig to show/hide or configure breadcrumb.
Metadata and OG
- metadata:
titleTemplate, description, twitterCard, etc. for SEO.
- og:
enabled, type ("dynamic" | "static"), endpoint for dynamic OG image generation. See API reference and OG Images docs.
Ordering (sidebar)
Use ordering: "numeric" (default) so sidebar order follows frontmatter order (numbers). Doc pages can set order: 1, order: 2, etc. in frontmatter to control order.
Edge cases
- Next.js: Must wrap config with
withDocs() from @farming-labs/next/config in next.config.ts.
- SvelteKit/Astro: Server-side docs loader must receive config and (for AI) env vars; see framework docs.
- Nuxt:
defineDocsHandler(config, useStorage) in server/api/docs.ts; config is imported from root docs.config.ts.
Resources
1---2name: configuration-23description: docs.config.ts options for @farming-labs/docs. Use when configuring entry, contentDir, theme, staticExport, nav, github, themeToggle, breadcrumb, sidebar, icons, components, metadata, og, onCopyClick, pageActions, or ai. Covers Next.js, SvelteKit, Astro, Nuxt config file location.4---56# @farming-labs/docs — Configuration78All configuration lives in a single **docs.config.ts** (or **docs.config.tsx**) file. Use this skill when editing or explaining config options.910**Full docs:** [Configuration](https://docs.farming-labs.dev/docs/configuration), [API Reference](https://docs.farming-labs.dev/docs/reference).1112---1314## Config file location by framework1516| Framework | Config path |17| --------- | ----------- |18| Next.js | Project root: `docs.config.ts` |19| SvelteKit | `src/lib/docs.config.ts` |20| Astro | `src/lib/docs.config.ts` |21| Nuxt | Project root: `docs.config.ts` |2223SvelteKit, Astro, and Nuxt require `contentDir` (path to markdown files) and `nav` (sidebar title and base URL) in addition to `entry` and `theme`.2425---2627## Main config options2829| Option | Type | Default | Description |30| ------ | ---- | ------- | ----------- |31| `entry` | `string` | `"docs"` | URL path prefix for docs (e.g. `"docs"` → `/docs`) |32| `contentDir` | `string` | same as `entry` | Path to content files (SvelteKit, Astro, Nuxt) |33| `staticExport` | `boolean` | `false` | Set `true` for full static builds; hides search and AI |34| `theme` | `DocsTheme` | — | Theme from a theme factory (e.g. `fumadocs()`, `pixelBorder()`) |35| `nav` | `{ title, url }` | — | Sidebar title and base URL (required for SvelteKit, Astro, Nuxt) |36| `github` | `string \| GithubConfig` | — | GitHub repo for "Edit on GitHub" and `{githubUrl}` in page actions |37| `themeToggle` | `boolean \| ThemeToggleConfig` | `true` | Light/dark mode toggle |38| `breadcrumb` | `boolean \| BreadcrumbConfig` | `true` | Breadcrumb navigation |39| `sidebar` | `boolean \| SidebarConfig` | `true` | Sidebar visibility and style |40| `icons` | `Record<string, Component>` | — | Icon registry for frontmatter `icon` fields |41| `components` | `Record<string, Component>` | — | Custom MDX components (e.g. `Callout`) |42| `onCopyClick` | `(data: CodeBlockCopyData) => void` | — | Callback when user copies a code block (title, content, url, language) |43| `pageActions` | `PageActionsConfig` | — | Copy Markdown, Open in LLM (see `page-actions` skill) |44| `ai` | `AIConfig` | — | RAG-powered AI chat (see `ask-ai` skill) |45| `metadata` | `DocsMetadata` | — | SEO: titleTemplate, description, etc. |46| `og` | `OGConfig` | — | Dynamic Open Graph images |4748---4950## Static export5152For fully static builds (e.g. Cloudflare Pages, no server):5354```ts55export default defineDocs({56 entry: "docs",57 staticExport: true,58 theme: fumadocs(),59});60```6162- Search (Cmd+K) and AI chat are hidden in the layout.63- Next.js: with `output: "export"` in `next.config`, the `/api/docs` route is not generated.64- Do not deploy the docs API route when using static export.6566---6768## GitHub (Edit on GitHub and openDocs)6970```ts71github: {72 url: "https://github.com/owner/repo",73 directory: "website", // optional: subdirectory where docs content lives74}75```7677Enables "Edit on GitHub" links and allows `{githubUrl}` in `pageActions.openDocs.providers`.7879---8081## Theme toggle8283```ts84themeToggle: {85 enabled: true, // show toggle (default)86 default: "light" | "dark" | "system",87}88```8990Set `enabled: false` to hide the toggle or force a single mode.9192---9394## Sidebar and breadcrumb9596- **sidebar:** `true` (default) or `SidebarConfig` (style, banner, footer, etc.). See customization docs for banner/footer content.97- **breadcrumb:** `true` (default) or `BreadcrumbConfig` to show/hide or configure breadcrumb.9899---100101## Metadata and OG102103- **metadata:** `titleTemplate`, `description`, `twitterCard`, etc. for SEO.104- **og:** `enabled`, `type` ("dynamic" | "static"), `endpoint` for dynamic OG image generation. See API reference and OG Images docs.105106---107108## Ordering (sidebar)109110Use `ordering: "numeric"` (default) so sidebar order follows frontmatter `order` (numbers). Doc pages can set `order: 1`, `order: 2`, etc. in frontmatter to control order.111112---113114## Edge cases1151161. **Next.js:** Must wrap config with `withDocs()` from `@farming-labs/next/config` in `next.config.ts`.1172. **SvelteKit/Astro:** Server-side docs loader must receive config and (for AI) env vars; see framework docs.1183. **Nuxt:** `defineDocsHandler(config, useStorage)` in `server/api/docs.ts`; config is imported from root `docs.config.ts`.119120---121122## Resources123124- **Configuration docs:** [docs.farming-labs.dev/docs/configuration](https://docs.farming-labs.dev/docs/configuration)125- **API Reference:** [docs.farming-labs.dev/docs/reference](https://docs.farming-labs.dev/docs/reference)126- **Related skills:** `ask-ai`, `page-actions`, `getting-started`, `creating-themes`.
farming-labs