mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
257cd3f8cb
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
394 lines
12 KiB
Plaintext
394 lines
12 KiB
Plaintext
---
|
|
title: "Appearance and branding"
|
|
description: "Configure theme, colors, logo, favicon, fonts, and background in docs.json to control the visual identity of your documentation site."
|
|
keywords: ["theme", "colors", "logo", "favicon", "fonts", "background", "appearance", "branding", "dark mode", "icons", "styling", "docs.json"]
|
|
---
|
|
|
|
import IconsOptional from "/snippets/icons-optional.mdx";
|
|
|
|
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
|
|
"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
|
|
"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
|
|
"favicon": "/favicon.svg"
|
|
```
|
|
|
|
---
|
|
|
|
### `appearance`
|
|
|
|
**Type:** `object`
|
|
|
|
Light/dark mode settings.
|
|
|
|
<ResponseField name="appearance.default" type='"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`.
|
|
</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
|
|
"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='"woff" | "woff2"'>
|
|
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
|
|
"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='"fontawesome" | "lucide" | "tabler"' 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
|
|
"icons": {
|
|
"library": "lucide"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `background`
|
|
|
|
**Type:** `object`
|
|
|
|
Background image, decoration, and color settings.
|
|
|
|
<ResponseField name="background.decoration" type='"gradient" | "grid" | "windows"'>
|
|
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
|
|
"background": {
|
|
"decoration": "gradient",
|
|
"color": {
|
|
"light": "#F8FAFC",
|
|
"dark": "#0F172A"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `styling`
|
|
|
|
**Type:** `object`
|
|
|
|
Fine-grained visual styling controls.
|
|
|
|
<ResponseField name="styling.eyebrows" type='"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`.
|
|
</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='"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](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
|
|
"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
|
|
"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
|
|
"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='"light" | "dark"'>
|
|
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
|
|
{
|
|
"$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"
|
|
}
|
|
}
|
|
```
|