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.

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

---

logo

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.

Show background.color

light · string

Background color for light mode. Must be a hex code beginning with #.

dark · string

Background color for dark mode. Must be a hex code beginning with #.

background.image · string or object

Background image for your site. Provide a single path or separate paths for light and dark mode.

Show background.image

light · string · required

Path to your background image for light mode. Example: /background.png.

dark · string · required

Path to your background image for dark mode. Example: /background-dark.png.

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

Show styling.codeblocks object

theme · string

A single Shiki theme for both modes.

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

theme · object

Separate Shiki themes for light and dark modes.

Show theme

light · string · required

Shiki theme name for light mode.

dark · string · required

Shiki theme name for dark mode.

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

languages · object

Custom language configuration for code blocks.

Show languages

custom · array of string

Paths to JSON files describing custom Shiki languages. Use this to add syntax highlighting for languages not in Shiki’s default set. Each file must follow the TextMate grammar format.

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

---

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.

Show thumbnails.fonts

family · string · required

Font family name, such as "Open Sans" or "Playfair Display". 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"
  }
}