Appearance and branding

Configure theme, colors, logo, favicon, fonts, and background in docs.json to control the visual identity of your documentation site.

Use these docs.json settings to control your documentation site's visual identity—layout theme, brand colors, logo, typography, and background.

The layout theme for your site.

One of: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma.

See Themes for previews and details.

Type: string

The name of your project, organization, or product. Appears in the browser tab title and other places throughout your site.

Type: object

The colors used in your documentation. Colors appear differently across themes. If you only provide a primary color, it applies to all color elements.

• colors.primary (string, required) — The primary color for your documentation. Generally used for emphasis in light mode, with some variation by theme.

Must be a hex code beginning with #. Example: "#0D9373".

• colors.light (string) — The color used for emphasis in dark mode.

Must be a hex code beginning with #.

• colors.dark (string) — The color used for buttons and hover states across both light and dark modes, with some variation by theme.

Must be a hex code beginning with #.

"colors": {
  "primary": "#0D9373",
  "light": "#55D799",
  "dark": "#0D9373"
}

Type: string or object

Your site logo. Provide a single image path or separate images for light and dark mode.

• logo.light (string, required) — Path to your logo file for light mode. Include the file extension. Example: /logo/light.svg.

• logo.dark (string, required) — Path to your logo file for dark mode. Include the file extension. Example: /logo/dark.svg.

• logo.href (string (uri)) — The URL to redirect to when clicking the logo. If not provided, the logo links to the first page of the currently selected locale for internationalized docs, or to your homepage for single-language sites. Example: https://yoursite.com.

"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg",
  "href": "https://yoursite.com"
}

Type: string or object

Path to your favicon file, including the file extension. Automatically resized to appropriate favicon sizes. Provide a single file or separate files for light and dark mode.

• favicon.light (string, required) — Path to your favicon for light mode. Include the file extension. Example: /favicon.png.

• favicon.dark (string, required) — Path to your favicon for dark mode. Include the file extension. Example: /favicon-dark.png.

"favicon": "/favicon.svg"

Type: object

Light/dark mode settings.

• appearance.default ("system" | "light" | "dark") — Default color mode. Choose system to match the user's OS setting, or light or dark to force a specific mode. Defaults to system.

• appearance.strict (boolean) — When true, hides the light/dark mode toggle so users cannot switch modes. Defaults to false.

"appearance": {
  "default": "dark",
  "strict": true
}

Type: object

Custom fonts for your documentation. The default font varies by theme. Supports Google Fonts and self-hosted fonts.

• fonts.family (string, required) — Font family name, such as "Inter" or "Open Sans". Supports Google Fonts family names—these load automatically without a source required.

• fonts.weight (number) — Font weight, such as 400 or 700. Variable fonts support fractional weights such as 550.

• fonts.source (string (uri)) — URL to a hosted font or a path to a local font file. Not needed for Google Fonts.

• Hosted: https://example.com/fonts/MyFont.woff2
• Local: /fonts/MyFont.woff2

• fonts.format ("woff" | "woff2") — Font file format. Required when using the source field.

• fonts.heading (object) — Override font settings for headings only.

Accepts the same family, weight, source, and format fields as the top-level fonts object.

• fonts.body (object) — Override font settings for body text only.

Accepts the same family, weight, source, and format fields as the top-level fonts object.

"fonts": {
  "family": "Inter",
  "heading": {
    "family": "Playfair Display"
  }
}

Type: object

Icon library settings. You can only use one icon library per project. All icon names in your docs must come from the selected library.

• icons.library ("fontawesome" | "lucide" | "tabler", required) — Icon library to use throughout your documentation. Defaults to fontawesome.

"icons": {
  "library": "lucide"
}

Type: object

Background image, decoration, and color settings.

• background.decoration ("gradient" | "grid" | "windows") — A decorative background pattern for your theme.

• background.color (object) — Custom background colors for light and dark modes.

• background.image (string or object) — Background image for your site. Provide a single path or separate paths for light and dark mode.

"background": {
  "decoration": "gradient",
  "color": {
    "light": "#F8FAFC",
    "dark": "#0F172A"
  }
}

Type: object

Fine-grained visual styling controls.

• styling.eyebrows ("section" | "breadcrumbs") — The style of the page eyebrow (the label shown at the top of the page). Choose section to show the section name or breadcrumbs to show the full navigation path. Defaults to section.

• styling.latex (boolean) — Controls whether LaTeX stylesheets load. By default, Mintlify automatically detects LaTeX usage in your content and loads the necessary stylesheets.

• Set to true to force-load LaTeX stylesheets when auto-detection fails.
• Set to false to prevent loading LaTeX stylesheets for better performance if you don't use math expressions.

• styling.codeblocks ("system" | "dark" | string | object) — Code block theme. Defaults to "system".

• "system": Matches the current site mode (light or dark)
• "dark": Always uses dark mode
• A Shiki theme name string: applies that theme to all code blocks
• An object with light and dark keys: applies separate Shiki themes per mode

"styling": {
  "codeblocks": {
    "theme": "dracula"
  }
}

"styling": {
  "codeblocks": {
    "theme": {
      "light": "github-light",
      "dark": "github-dark"
    }
  }
}

"styling": {
  "codeblocks": {
    "languages": {
      "custom": ["/languages/my-language.json"]
    }
  }
}

Type: object

Thumbnail customization for social media and page previews.

• thumbnails.appearance ("light" | "dark") — Visual theme for thumbnails. If not set, thumbnails use your site's color scheme defined by colors.

• thumbnails.background (string) — Background image for thumbnails. Can be a relative path or absolute URL.

• thumbnails.fonts (object) — Font configuration for thumbnails. Only supports Google Fonts family names.

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "colors": {
    "primary": "#3B82F6",
    "light": "#93C5FD",
    "dark": "#1D4ED8"
  },
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg",
    "href": "https://example.com"
  },
  "favicon": "/favicon.svg",
  "appearance": {
    "default": "system"
  },
  "fonts": {
    "family": "Inter"
  },
  "icons": {
    "library": "lucide"
  },
  "background": {
    "decoration": "gradient"
  }
}

• docs.json schema reference
• Global settings
• Themes