creating-themes

name	creating-themes
description	Create and share a custom theme for @farming-labs/docs. Use when building a theme with createTheme(), extendTheme(), cherry-picking built-in defaults, publishing as npm package, or adding CSS overrides. Covers ui.colors, typography, layout, sidebar, radius, and package layout for publishing.

@farming-labs/docs — Creating and Sharing Themes

Use this skill when: the user wants to create a custom theme, extend an existing theme, or publish/share a theme (e.g. as npm). For general setup (init, install, docs.config), use the getting-started skill.

Full guide: Creating your own theme.

---

Quick: create a theme

import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-theme",
  ui: {
    colors: {
      primary: "#e11d48",
      background: "#09090b",
      foreground: "#fafafa",
      muted: "#71717a",
      border: "#27272a",
    },
    radius: "0.5rem",
  },
});

Use in docs.config:

import { defineDocs } from "@farming-labs/docs";
import { myTheme } from "./my-theme";

export default defineDocs({
  entry: "docs",
  theme: myTheme(),
});

Users can override: theme: myTheme({ ui: { colors: { primary: "#3b82f6" } } }).

---

Extend an existing theme

Use extendTheme() to build on a built-in preset:

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

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

For other frameworks use the same framework's theme package (e.g. @farming-labs/svelte-theme, @farming-labs/astro-theme, @farming-labs/nuxt-theme). You can extend any built-in: fumadocs, darksharp, pixelBorder, colorful, greentree, darkbold, shiny.

Important: extendTheme() returns a theme instance (not a factory). Use createTheme() when you want a reusable preset that others call as myTheme().

---

Config options (createTheme / extendTheme)

Area	Key options
name	Unique string (e.g. "my-theme") for debugging and CSS scoping.
ui.colors	primary, primaryForeground, background, foreground, muted, mutedForeground, border, card, cardForeground, accent, accentForeground, secondary, secondaryForeground, popover, popoverForeground, ring. Any valid CSS color (hex, rgb, hsl, oklch).
ui.typography	font.style.sans, font.style.mono, font.h1–h4, font.body, font.small (size, weight, lineHeight, letterSpacing).
ui.radius	Global radius: "0.5rem", "0px", "0.75rem".
ui.layout	contentWidth, sidebarWidth, tocWidth, toc.enabled, toc.depth, header.height, header.sticky.
ui.codeBlock	showLineNumbers, showCopyButton, theme, darkTheme.
ui.sidebar	style: "default" | "bordered" | "floating", background, borderColor.
ui.card	bordered, background.
components	e.g. Callout: { variant: "outline" }.

Only set what you want to change; the rest is inherited.

---

Cherry-pick from built-in themes

Mix defaults from different built-in themes:

import { DefaultUIDefaults } from "@farming-labs/theme/default";
import { DarksharpUIDefaults } from "@farming-labs/theme/darksharp";
import { PixelBorderUIDefaults } from "@farming-labs/theme/pixel-border";
import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-hybrid-theme",
  ui: {
    colors: PixelBorderUIDefaults.colors,
    typography: DefaultUIDefaults.typography,
    layout: DarksharpUIDefaults.layout,
    sidebar: { style: "floating" },
  },
});

Export your own defaults so others can extend: export { MyThemeDefaults };.

---

Publishing as an npm package

Package layout

my-fumadocs-theme/
  src/
    index.ts       ← createTheme() and exports
    theme.css      ← optional CSS overrides
  package.json

package.json (minimal)

{
  "name": "my-fumadocs-theme",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": { "import": "./dist/index.mjs", "types": "./dist/index.d.mts" },
    "./css": "./src/theme.css"
  },
  "peerDependencies": {
    "@farming-labs/docs": ">=0.0.1"
  }
}

If the theme has no CSS, omit the "./css" export. If it does, users import it in their global CSS (Next: app/global.css, SvelteKit: src/app.css, Nuxt: css in nuxt.config.ts, Astro: in layout or page).

How users install and use

npm install my-fumadocs-theme
# or pnpm add / yarn add / bun add

import { myTheme } from "my-fumadocs-theme";

export default defineDocs({
  entry: "docs",
  theme: myTheme(),
});

@import "tailwindcss";
@import "my-fumadocs-theme/css";

---

Optional: custom CSS file

For pixel-level control (sidebar, code blocks, callouts), ship a theme.css that:

1. Imports a base preset: @import "@farming-labs/theme/presets/black"; or @import "@farming-labs/theme/presets/neutral";
2. Overrides --color-fd-* and other variables in :root and .dark
3. Targets component selectors (e.g. aside#nd-sidebar, a[data-active]) as needed

See the Creating your own theme doc for the full list of selectors and presets.

---

Resources

• Full guide: docs.farming-labs.dev/docs/themes/creating-themes
• Themes overview: docs.farming-labs.dev/docs/themes
• Repo: github.com/farming-labs/docs