Appearance and branding

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.

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

string

The color used for emphasis in dark mode.Must be a hex code beginning with #.

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.

string

required

Path to your logo file for light mode. Include the file extension. Example: /logo/light.svg.

string

required

Path to your logo file for dark mode. Include the file extension. Example: /logo/dark.svg.

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. Accepts an absolute URL, such as https://yoursite.com, or a relative path that starts with /, such as /quickstart.

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.

string

required

Path to your favicon for light mode. Include the file extension. Example: /favicon.png.

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.

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

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.

string

required

Font family name, such as "Inter" or "Open Sans". Supports Google Fonts family names. These load automatically without requiring a source.

number

Font weight, such as 400 or 700. Variable fonts support fractional weights such as 550.

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

"woff" | "woff2"

Font file format. Required when using the source field.

object

Override font settings for headings only.Accepts the same family, weight, source, and format fields as the top-level fonts object.

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.

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

"gradient" | "grid" | "windows"

A decorative background pattern for your theme.

object

Custom background colors for light and dark modes.

Show background.color

string

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

string

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

string or object

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

Show background.image

string

required

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

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.

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

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.

"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

string

A single Shiki theme for both modes.

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

object

Separate Shiki themes for light and dark modes.

Show theme

string

required

Shiki theme name for light mode.

string

required

Shiki theme name for dark mode.

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

object

Custom language configuration for code blocks.

Show languages

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.

"classic" | "headline" | "minimal"

Layout for thumbnails. If not set, thumbnails use the default layout.

classic: Logo in the top left, with the title and description below it.
headline: Title and description at the top, with the logo in the bottom right.
minimal: Centered title and description, with the logo in a panel at the bottom.

With a preset, the eyebrow above the title always uses a monospace font, even if you set thumbnails.fonts.

"light" | "dark"

Visual theme for thumbnails. If not set, thumbnails use your site’s color scheme defined by colors.

"brand" | "neutral"

Background style for preset thumbnails. Only applies when you set thumbnails.preset. Defaults to brand.

brand: A background and glow tinted with the hue of your primary color. If you set background.color, thumbnails use that color as the background.
neutral: Your site’s background color, with no glow.

string

Background image for thumbnails. Can be a relative path or absolute URL. On preset thumbnails, the image replaces the background color and glow from thumbnails.surface.

object

Font configuration for thumbnails. Uses a Google Fonts family or a self-hosted font file. If the font fails to load, thumbnails use the default font.

Show thumbnails.fonts

string

required

Font family name, such as "Open Sans" or "Playfair Display". Supports Google Fonts family names. If you set source, this is the name of your self-hosted font.

string

URL or path to a self-hosted font file, such as /fonts/custom.woff or https://cdn.example.com/font.woff.

"woff" | "ttf" | "otf"

Format of the self-hosted font file. Required when you set source. Thumbnails do not support woff2.

object

The label shown above the page title in thumbnails.

Show thumbnails.eyebrow

The navigation level whose name appears as the eyebrow. Defaults to group. If a page is not inside a navigation element of the chosen type, the eyebrow shows the group name instead. Set to none to hide the eyebrow.

"plain" | "bar" | "pill"

How the eyebrow is drawn on preset thumbnails. Defaults to bar for classic, pill for headline, and plain for minimal.

string

Hex color of the eyebrow on preset thumbnails. If not set, Mintlify derives the color from your theme colors.

docs.json

"thumbnails": {
  "preset": "headline",
  "eyebrow": {
    "source": "tab",
    "style": "bar",
    "color": "#FDE68A"
  }
}

Override thumbnails for a page or section

To change the thumbnail for one page, add a thumbnail object to the page frontmatter. To change it for a navigation section, add thumbnail to a group, tab, anchor, dropdown, product, version, language, or menu item in docs.json. A thumbnail override accepts preset, appearance, surface, background, and eyebrow. In an override, eyebrow is the literal text shown above the title, and "" hides it. Set background to "" to remove an inherited background image. Eyebrow source, style, and color are only set site-wide in thumbnails.eyebrow. Mintlify resolves each key separately. It uses the page frontmatter first, then the nearest navigation section that sets the key, then thumbnails in docs.json. Mintlify ignores invalid override values and uses the next layer instead.

Page frontmatter

---
title: "Webhooks"
thumbnail:
  preset: minimal
  eyebrow: "API Reference"
---

docs.json

{
  "group": "Webhooks",
  "thumbnail": { "preset": "minimal" },
  "pages": ["guides/webhooks"]
}

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

Get started

Create content

Manage your site

Agent

Assistant

Agent-ready content

Search and SEO

Document APIs

Integrations

Reference

Appearance and branding

Settings

`theme` - required

`name` - required

`colors` - required

`logo`

`favicon`

`appearance`

`fonts`

`icons`

`background`

`styling`

`thumbnails`

Override thumbnails for a page or section

Example

​Settings

​theme - required

​name - required

​colors - required

​logo

​favicon

​appearance

​fonts

​icons

​background

​styling

​thumbnails

​Override thumbnails for a page or section

​Example

Settings

`theme` - required

`name` - required

`colors` - required

`logo`

`favicon`

`appearance`

`fonts`

`icons`

`background`

`styling`

`thumbnails`

Override thumbnails for a page or section

Example