外观与品牌

使用这些 docs.json 设置来控制文档站点的视觉标识：布局主题、品牌颜色、logo、字体和背景。

设置

`theme` - 必需

站点的布局主题。可选值：mint、maple、palm、willow、linden、almond、aspen、sequoia、luma。详情请参阅主题的预览和说明。

`name` - 必需

类型： string 你的项目、组织或产品的名称。显示在浏览器标签标题和站点的其他位置。

`colors` - 必需

类型： object 文档中使用的颜色。不同主题对颜色的显示方式不同。如果你只提供主色，它将应用于所有颜色元素。

string

必填

文档的主色。通常在浅色模式下用于强调，具体因主题而异。必须是以 # 开头的十六进制代码。示例："#0D9373"。

string

在深色模式下用于强调的颜色。必须是以 # 开头的十六进制代码。

string

在浅色和深色模式下用于按钮和悬停状态的颜色，具体因主题而异。必须是以 # 开头的十六进制代码。

docs.json

"colors": {
  "primary": "#0D9373",
  "light": "#55D799",
  "dark": "#0D9373"
}

`logo`

类型： string 或 object 站点的 logo。提供单个图片路径或为浅色和深色模式提供单独的图片。

string

必填

浅色模式下 logo 文件的路径。包含文件扩展名。示例：/logo/light.svg。

string

必填

深色模式下 logo 文件的路径。包含文件扩展名。示例：/logo/dark.svg。

string (uri)

点击 logo 时重定向到的 URL。如果未提供，对于国际化文档，logo 链接到当前所选区域设置的第一页，对于单语言站点则链接到首页。可接受绝对 URL（例如 https://yoursite.com），也可接受以 / 开头的相对路径（例如 /quickstart）。

docs.json

"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg",
  "href": "https://yoursite.com"
}

`favicon`

类型： string 或 object favicon 文件的路径，包含文件扩展名。会自动调整为适当的 favicon 尺寸。提供单个文件或为浅色和深色模式提供单独的文件。

string

必填

浅色模式下 favicon 的路径。包含文件扩展名。示例：/favicon.png。

string

必填

深色模式下 favicon 的路径。包含文件扩展名。示例：/favicon-dark.png。

docs.json

"favicon": "/favicon.svg"

`appearance`

类型： object 浅色/深色模式设置。

"system" | "light" | "dark"

默认颜色模式。选择 system 以匹配用户操作系统设置，或选择 light 或 dark 强制使用特定模式。默认为 system。

boolean

当为 true 时，隐藏浅色/深色模式切换，使用户无法切换模式。默认为 false。

docs.json

"appearance": {
  "default": "dark",
  "strict": true
}

`fonts`

类型： object 文档的自定义字体。默认字体因主题而异。支持 Google Fonts 和自托管字体。

string

必填

字体系列名称，如 "Inter" 或 "Open Sans"。支持 Google Fonts 系列名称。这些字体会自动加载，无需提供 source。

number

字体粗细，如 400 或 700。可变字体支持小数粗细，如 550。

string (uri)

托管字体的 URL 或本地字体文件的路径。Google Fonts 不需要此项。

托管：https://example.com/fonts/MyFont.woff2
本地：/fonts/MyFont.woff2

"woff" | "woff2"

字体文件格式。使用 source 字段时必需。

object

仅用于标题的字体设置覆盖。接受与顶级 fonts 对象相同的 family、weight、source 和 format 字段。

object

仅用于正文的字体设置覆盖。接受与顶级 fonts 对象相同的 family、weight、source 和 format 字段。

docs.json

"fonts": {
  "family": "Inter",
  "heading": {
    "family": "Playfair Display"
  }
}

`icons`

类型： object 图标库设置。每个项目只能使用一个图标库。文档中的所有图标名称必须来自所选的图标库。

"fontawesome" | "lucide" | "tabler"

必填

在整个文档中使用的图标库。默认为 fontawesome。

无论库设置如何，你可以为任何单个图标指定指向外部托管图标的 URL 或项目中图标文件的路径。

docs.json

"icons": {
  "library": "lucide"
}

`background`

类型： object 背景图片、装饰和颜色设置。

"gradient" | "grid" | "windows"

主题的装饰背景图案。

object

浅色和深色模式的自定义背景颜色。

显示 background.color

string

浅色模式的背景颜色。必须是以 # 开头的十六进制代码。

string

深色模式的背景颜色。必须是以 # 开头的十六进制代码。

string 或 object

站点的背景图片。提供单个路径或为浅色和深色模式提供单独的路径。

显示 background.image

string

必填

浅色模式背景图片的路径。示例：/background.png。

string

必填

深色模式背景图片的路径。示例：/background-dark.png。

docs.json

"background": {
  "decoration": "gradient",
  "color": {
    "light": "#F8FAFC",
    "dark": "#0F172A"
  }
}

`styling`

类型： object 精细的视觉样式控制。

"section" | "breadcrumbs"

页面 eyebrow 的样式（页面顶部显示的标签）。选择 section 显示章节名称，或选择 breadcrumbs 显示完整导航路径。默认为 section。

boolean

控制是否加载 LaTeX 样式表。默认情况下，Mintlify 会自动检测内容中的 LaTeX 使用并加载必要的样式表。

设置为 true 可在自动检测失败时强制加载 LaTeX 样式表。
如果你不使用数学表达式，设置为 false 可阻止加载 LaTeX 样式表以提高性能。

"system" | "dark" | string | object

代码块主题。默认为 "system"。

"system"：匹配当前站点模式（浅色或深色）
"dark"：始终使用深色模式
Shiki 主题名称字符串：将该主题应用于所有代码块
带有 light 和 dark 键的对象：为每种模式应用单独的 Shiki 主题

显示 styling.codeblocks object

string

用于两种模式的单个 Shiki 主题。

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

object

为浅色和深色模式分别设置 Shiki 主题。

显示 theme

string

必填

浅色模式的 Shiki 主题名称。

string

必填

深色模式的 Shiki 主题名称。

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

object

代码块的自定义语言配置。

显示 languages

string 数组

描述自定义 Shiki 语言的 JSON 文件路径。用于为 Shiki 默认集中没有的语言添加语法高亮。每个文件必须遵循 TextMate 语法格式。

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

`thumbnails`

类型： object 社交媒体和页面预览的缩略图自定义。

"classic" | "headline" | "minimal"

缩略图的布局。如果未设置，缩略图使用默认布局。

classic：logo 位于左上角，标题和描述位于其下方。
headline：标题和描述位于顶部，logo 位于右下角。
minimal：标题和描述居中，logo 位于底部的面板中。

使用预设时，标题上方的眉标（eyebrow）始终使用等宽字体，即使你设置了 thumbnails.fonts。

"light" | "dark"

缩略图的视觉主题。如果未设置，缩略图使用 colors 定义的站点配色方案。

"brand" | "neutral"

使用预设的缩略图的背景样式。仅在设置了 thumbnails.preset 时生效。默认为 brand。

brand：使用主色调色相着色的背景和光晕。如果你设置了 background.color，缩略图会使用该颜色作为背景。
neutral：使用站点的背景色，不带光晕。

string

缩略图的背景图片。可以是相对路径或绝对 URL。在使用预设的缩略图上，该图片会替换 thumbnails.surface 的背景色和光晕。

object

缩略图的字体配置。可使用 Google Fonts 字体系列或自托管字体文件。如果字体加载失败，缩略图会使用默认字体。

显示 thumbnails.fonts

string

必填

字体系列名称，如 "Open Sans" 或 "Playfair Display"。支持 Google Fonts 系列名称。如果设置了 source，则为你的自托管字体名称。

string

自托管字体文件的 URL 或路径，如 /fonts/custom.woff 或 https://cdn.example.com/font.woff。

"woff" | "ttf" | "otf"

自托管字体文件的格式。设置 source 时必填。缩略图不支持 woff2。

object

缩略图中显示在页面标题上方的标签。

显示 thumbnails.eyebrow

其名称作为眉标显示的导航层级。默认为 group。如果页面不在所选类型的导航元素中，眉标会显示分组名称。设置为 none 可隐藏眉标。

"plain" | "bar" | "pill"

眉标在使用预设的缩略图上的绘制方式。classic 默认为 bar，headline 默认为 pill，minimal 默认为 plain。

string

眉标在使用预设的缩略图上的十六进制颜色。如果未设置，Mintlify 会根据你的主题颜色生成颜色。

docs.json

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

为页面或分区覆盖缩略图

要更改单个页面的缩略图，请在页面 frontmatter 中添加 thumbnail 对象。要更改某个导航分区的缩略图，请在 docs.json 中为分组、标签页、锚点、下拉菜单、产品、版本、语言或菜单项添加 thumbnail。 thumbnail 覆盖支持 preset、appearance、surface、background 和 eyebrow。在覆盖中，eyebrow 是显示在标题上方的文字本身，设置为 "" 会隐藏它。将 background 设置为 "" 可移除继承的背景图片。眉标的 source、style 和 color 只能在 thumbnails.eyebrow 中为整个站点设置。 Mintlify 会分别解析每个键：先使用页面 frontmatter，再使用设置了该键的最近导航分区，然后使用 docs.json 中的 thumbnails。Mintlify 会忽略无效的覆盖值，并使用下一层的值。

Page frontmatter

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

docs.json

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

示例

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

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

设置

`theme` - 必需

`name` - 必需

`colors` - 必需

`logo`

`favicon`

`appearance`

`fonts`

`icons`

`background`

`styling`

`thumbnails`

为页面或分区覆盖缩略图

示例

​设置

​theme - 必需

​name - 必需

​colors - 必需

​logo

​favicon

​appearance

​fonts

​icons

​background

​styling

​thumbnails

​为页面或分区覆盖缩略图

​示例

设置

`theme` - 必需

`name` - 必需

`colors` - 必需

`logo`

`favicon`

`appearance`

`fonts`

`icons`

`background`

`styling`

`thumbnails`

为页面或分区覆盖缩略图

示例