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

​
Settings

​
theme - required

The layout theme for your site. One of: mint, maple, palm, willow, linden, almond, aspen, sequoia, luma. See Themes for previews and details.

​
name - required

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

​
colors - required

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 #.
docs.json
"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.
docs.json
"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg",
  "href": "https://yoursite.com"
}

​
favicon

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.
docs.json
"favicon": "/favicon.svg"

​
appearance

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.
docs.json
"appearance": {
  "default": "dark",
  "strict": true
}

​
fonts

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.
docs.json
"fonts": {
  "family": "Inter",
  "heading": {
    "family": "Playfair Display"
  }
}

​
icons

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.
You can specify a URL to an externally hosted icon or a path to an icon file in your project for any individual icon, regardless of the library setting.
docs.json
"icons": {
  "library": "lucide"
}

​
background

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.
docs.json
"background": {
  "decoration": "gradient",
  "color": {
    "light": "#F8FAFC",
    "dark": "#0F172A"
  }
}

​
styling

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 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

​
thumbnails

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.

​
Example

docs.json
{
  "$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"
  }
}