> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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` - <Badge color="red">required</Badge>

The layout theme for your site.

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

See [Themes](/customize/themes) for previews and details.

***

### `name` - <Badge color="red">required</Badge>

**Type:** `string`

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

***

### `colors` - <Badge color="red">required</Badge>

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

<ResponseField name="colors.primary" type="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"`.
</ResponseField>

<ResponseField name="colors.light" type="string">
  The color used for emphasis in dark mode.

  Must be a hex code beginning with `#`.
</ResponseField>

<ResponseField name="colors.dark" type="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 `#`.
</ResponseField>

```json docs.json theme={null}
"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.

<ResponseField name="logo.light" type="string" required>
  Path to your logo file for light mode. Include the file extension. Example: `/logo/light.svg`.
</ResponseField>

<ResponseField name="logo.dark" type="string" required>
  Path to your logo file for dark mode. Include the file extension. Example: `/logo/dark.svg`.
</ResponseField>

<ResponseField name="logo.href" type="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](/guides/internationalization), or to your homepage for single-language sites. Example: `https://yoursite.com`.
</ResponseField>

```json docs.json theme={null}
"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.

<ResponseField name="favicon.light" type="string" required>
  Path to your favicon for light mode. Include the file extension. Example: `/favicon.png`.
</ResponseField>

<ResponseField name="favicon.dark" type="string" required>
  Path to your favicon for dark mode. Include the file extension. Example: `/favicon-dark.png`.
</ResponseField>

```json docs.json theme={null}
"favicon": "/favicon.svg"
```

***

### `appearance`

**Type:** `object`

Light/dark mode settings.

<ResponseField name="appearance.default" type="&#x22;system&#x22; | &#x22;light&#x22; | &#x22;dark&#x22;">
  Default color mode. Choose `system` to match the user's OS setting, or `light` or `dark` to force a specific mode. Defaults to `system`.
</ResponseField>

<ResponseField name="appearance.strict" type="boolean">
  When `true`, hides the light/dark mode toggle so users cannot switch modes. Defaults to `false`.
</ResponseField>

```json docs.json theme={null}
"appearance": {
  "default": "dark",
  "strict": true
}
```

***

### `fonts`

**Type:** `object`

Custom fonts for your documentation. The default font varies by theme. Supports [Google Fonts](https://fonts.google.com) and self-hosted fonts.

<ResponseField name="fonts.family" type="string" required>
  Font family name, such as `"Inter"` or `"Open Sans"`. Supports [Google Fonts](https://fonts.google.com) family names—these load automatically without a `source` required.
</ResponseField>

<ResponseField name="fonts.weight" type="number">
  Font weight, such as `400` or `700`. Variable fonts support fractional weights such as `550`.
</ResponseField>

<ResponseField name="fonts.source" type="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`
</ResponseField>

<ResponseField name="fonts.format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
  Font file format. Required when using the `source` field.
</ResponseField>

<ResponseField name="fonts.heading" type="object">
  Override font settings for headings only.

  Accepts the same `family`, `weight`, `source`, and `format` fields as the top-level `fonts` object.
</ResponseField>

<ResponseField name="fonts.body" type="object">
  Override font settings for body text only.

  Accepts the same `family`, `weight`, `source`, and `format` fields as the top-level `fonts` object.
</ResponseField>

```json docs.json theme={null}
"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.

<ResponseField name="icons.library" type="&#x22;fontawesome&#x22; | &#x22;lucide&#x22; | &#x22;tabler&#x22;" required>
  Icon library to use throughout your documentation. Defaults to `fontawesome`.

  <Note>
    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.
  </Note>
</ResponseField>

```json docs.json theme={null}
"icons": {
  "library": "lucide"
}
```

***

### `background`

**Type:** `object`

Background image, decoration, and color settings.

<ResponseField name="background.decoration" type="&#x22;gradient&#x22; | &#x22;grid&#x22; | &#x22;windows&#x22;">
  A decorative background pattern for your theme.
</ResponseField>

<ResponseField name="background.color" type="object">
  Custom background colors for light and dark modes.

  <Expandable title="background.color">
    <ResponseField name="light" type="string">
      Background color for light mode. Must be a hex code beginning with `#`.
    </ResponseField>

    <ResponseField name="dark" type="string">
      Background color for dark mode. Must be a hex code beginning with `#`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="background.image" type="string or object">
  Background image for your site. Provide a single path or separate paths for light and dark mode.

  <Expandable title="background.image">
    <ResponseField name="light" type="string" required>
      Path to your background image for light mode. Example: `/background.png`.
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      Path to your background image for dark mode. Example: `/background-dark.png`.
    </ResponseField>
  </Expandable>
</ResponseField>

```json docs.json theme={null}
"background": {
  "decoration": "gradient",
  "color": {
    "light": "#F8FAFC",
    "dark": "#0F172A"
  }
}
```

***

### `styling`

**Type:** `object`

Fine-grained visual styling controls.

<ResponseField name="styling.eyebrows" type="&#x22;section&#x22; | &#x22;breadcrumbs&#x22;">
  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`.
</ResponseField>

<ResponseField name="styling.latex" type="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.
</ResponseField>

<ResponseField name="styling.codeblocks" type="&#x22;system&#x22; | &#x22;dark&#x22; | 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](https://shiki.style/themes) name string: applies that theme to all code blocks
  * An object with `light` and `dark` keys: applies separate Shiki themes per mode

  <Expandable title="styling.codeblocks object">
    <ResponseField name="theme" type="string">
      A single Shiki theme for both modes.

      ```json theme={null}
      "styling": {
        "codeblocks": {
          "theme": "dracula"
        }
      }
      ```
    </ResponseField>

    <ResponseField name="theme" type="object">
      Separate Shiki themes for light and dark modes.

      <Expandable title="theme">
        <ResponseField name="light" type="string" required>
          Shiki theme name for light mode.
        </ResponseField>

        <ResponseField name="dark" type="string" required>
          Shiki theme name for dark mode.
        </ResponseField>
      </Expandable>

      ```json theme={null}
      "styling": {
        "codeblocks": {
          "theme": {
            "light": "github-light",
            "dark": "github-dark"
          }
        }
      }
      ```
    </ResponseField>

    <ResponseField name="languages" type="object">
      Custom language configuration for code blocks.

      <Expandable title="languages">
        <ResponseField name="custom" type="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](https://macromates.com/manual/en/language_grammars).

          ```json theme={null}
          "styling": {
            "codeblocks": {
              "languages": {
                "custom": ["/languages/my-language.json"]
              }
            }
          }
          ```
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

### `thumbnails`

**Type:** `object`

Thumbnail customization for social media and page previews.

<ResponseField name="thumbnails.appearance" type="&#x22;light&#x22; | &#x22;dark&#x22;">
  Visual theme for thumbnails. If not set, thumbnails use your site's color scheme defined by `colors`.
</ResponseField>

<ResponseField name="thumbnails.background" type="string">
  Background image for thumbnails. Can be a relative path or absolute URL.
</ResponseField>

<ResponseField name="thumbnails.fonts" type="object">
  Font configuration for thumbnails. Only supports Google Fonts family names.

  <Expandable title="thumbnails.fonts">
    <ResponseField name="family" type="string" required>
      Font family name, such as `"Open Sans"` or `"Playfair Display"`. Supports [Google Fonts](https://fonts.google.com) family names.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```json docs.json theme={null}
{
  "$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"
  }
}
```


## Related topics

- [Configurations](/docs/editor/configurations.md)
- [docs.json schema reference](/docs/organize/settings-reference.md)
- [Global settings](/docs/organize/settings.md)