Theming and branding

Customize colors, logos, fonts, and appearance for your documentation site.

You control the visual identity of your docs through the colors, logo, favicon, fonts, and appearance fields in docs.json. This page covers each theming option in detail.

Colors

The colors object defines your brand palette. Only primary is required -- all other values are derived automatically if omitted.

{
  "colors": {
    "primary": "#0D9373",
    "light": "#CFF6EE",
    "dark": "#0C3A33"
  }
}

Field	Type	Description	Required
`primary`	string	Primary brand color used for links, buttons, and accents. Must be a hex value.	Yes
`light`	string	Light variant used for light-mode backgrounds and highlights.	Yes
`dark`	string	Dark variant used for dark-mode accents.	Yes
`background`	string	Page background color override.	Yes
`border`	string	Border color override for cards, dividers, and other elements.	Yes
`muted`	string	Muted text and secondary element color.	Yes
`surface`	string	Surface color for cards, code blocks, and elevated elements.	Yes

All color values should be hex codes (e.g., #0D9373). The derived colors work well for most brands, so start with just primary and customize from there.

Logo

The logo field sets the image displayed in the navbar. You can provide a single URL or separate light/dark variants.

{
  "logo": {
    "light": "/images/logo-light.svg",
    "dark": "/images/logo-dark.svg"
  }
}

Field	Type	Description	Required
`light`	string	Logo image path or URL for light mode.	Yes
`dark`	string	Logo image path or URL for dark mode.	Yes
`alt`	string	Alt text for the logo image.	Yes
`href`	string	URL the logo links to when clicked. Defaults to your docs homepage.	Yes

Use SVG logos for the best quality at all screen sizes. Place logo files in your docs directory and reference them with a relative path like /images/logo.svg.

Favicon

The favicon field sets the browser tab icon. Like logos, you can provide a single path or light/dark variants.

{
  "favicon": "/images/favicon.svg"
}

Fonts

The fonts object controls typography across your site. You can set separate families for headings, body text, and monospace code.

{
  "fonts": {
    "heading": "Inter",
    "body": "Inter",
    "mono": "JetBrains Mono",
    "provider": "google"
  }
}

Field	Type	Description	Required
`heading`	string	Font family for headings (h1-h6).	Yes
`body`	string	Font family for body text and paragraphs.	Yes
`mono`	string	Font family for inline code and code blocks.	Yes
`provider`	'google' \| 'local' \| 'custom'	Font loading strategy. `google` loads from Google Fonts, `local` uses self-hosted files, `custom` uses a CSS URL.	Yes
`cssUrl`	string	URL to a custom CSS file that defines `@font-face` rules. Use with `provider: 'custom'`.	Yes

Advanced font objects

For fine-grained control, you can use font objects instead of strings. This is useful for self-hosted fonts or when you need specific weights.

{
  "fonts": {
    "heading": {
      "family": "Cal Sans",
      "source": "/fonts/CalSans-SemiBold.woff2",
      "format": "woff2",
      "weight": 600
    },
    "body": {
      "family": "Inter",
      "source": "/fonts/Inter-Regular.woff2",
      "format": "woff2",
      "weight": 400

Field	Type	Description	Required
`family`	string	CSS font-family name.	Yes
`source`	string	Path or URL to the font file.	Yes
`format`	'woff' \| 'woff2'	Font file format hint for the browser.	Yes
`weight`	number	Numeric font weight (e.g., 400 for regular, 700 for bold).	Yes

Using Google Fonts

Set provider to google and specify font family names. Blode.md automatically loads the fonts from Google Fonts CDN.

{
  "fonts": {
    "heading": "Poppins",
    "body": "Open Sans",
    "provider": "google"
  }
}

Using a custom CSS URL

If you host your own font CSS (or use a service like Adobe Fonts), set provider to custom and provide the cssUrl.

{
  "fonts": {
    "heading": "MyCustomFont",
    "body": "MyCustomFont",
    "provider": "custom",
    "cssUrl": "https://fonts.example.com/my-custom-font.css"
  }
}

Appearance

The appearance object controls dark/light mode behavior.

{
  "appearance": {
    "default": "system",
    "strict": false
  }
}

Field	Type	Description	Required	Default
`default`	'dark' \| 'light' \| 'system'	Initial color mode when a visitor first loads the site.	Yes	'system'
`strict`	boolean	When `true`, locks the site to the `default` mode and hides the theme toggle. Useful for brand-specific designs.	Yes	false

Theme

The top-level theme field selects the overall visual template for your docs. Set it to a theme name like mint.

{
  "theme": "mint"
}

Complete example

Here is a fully themed docs.json:

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "my-project",
  "theme": "mint",
  "colors": {
    "primary": "#6366F1",
    "light": "#E0E7FF",
    "dark": "#312E81",
    "background": "#FAFAFA",
    "surface": "#F3F4F6"
  },
  "logo": {
    "light":