> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 外观与品牌

> 在 docs.json 中配置主题、颜色、logo、favicon、字体和背景。

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

## 设置

### `theme` - <Badge color="red">必需</Badge>

站点的布局主题。

可选值：`mint`、`maple`、`palm`、`willow`、`linden`、`almond`、`aspen`、`sequoia`、`luma`。

详情请参阅[主题](/zh/customize/themes)的预览和说明。

***

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

**类型：** `string`

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

***

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

**类型：** `object`

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

<ResponseField name="colors.primary" type="string" required>
  文档的主色。通常在浅色模式下用于强调，具体因主题而异。

  必须是以 `#` 开头的十六进制代码。示例：`"#0D9373"`。
</ResponseField>

<ResponseField name="colors.light" type="string">
  在深色模式下用于强调的颜色。

  必须是以 `#` 开头的十六进制代码。
</ResponseField>

<ResponseField name="colors.dark" type="string">
  在浅色和深色模式下用于按钮和悬停状态的颜色，具体因主题而异。

  必须是以 `#` 开头的十六进制代码。
</ResponseField>

```json docs.json theme={null}
"colors": {
  "primary": "#0D9373",
  "light": "#55D799",
  "dark": "#0D9373"
}
```

***

### `logo`

**类型：** `string` 或 `object`

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

<ResponseField name="logo.light" type="string" required>
  浅色模式下 logo 文件的路径。包含文件扩展名。示例：`/logo/light.svg`。
</ResponseField>

<ResponseField name="logo.dark" type="string" required>
  深色模式下 logo 文件的路径。包含文件扩展名。示例：`/logo/dark.svg`。
</ResponseField>

<ResponseField name="logo.href" type="string (uri)">
  点击 logo 时重定向到的 URL。如果未提供，对于[国际化文档](/zh/guides/internationalization)，logo 链接到当前所选区域设置的第一页，对于单语言站点则链接到首页。示例：`https://yoursite.com`。
</ResponseField>

```json docs.json theme={null}
"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg",
  "href": "https://yoursite.com"
}
```

***

### `favicon`

**类型：** `string` 或 `object`

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

<ResponseField name="favicon.light" type="string" required>
  浅色模式下 favicon 的路径。包含文件扩展名。示例：`/favicon.png`。
</ResponseField>

<ResponseField name="favicon.dark" type="string" required>
  深色模式下 favicon 的路径。包含文件扩展名。示例：`/favicon-dark.png`。
</ResponseField>

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

***

### `appearance`

**类型：** `object`

浅色/深色模式设置。

<ResponseField name="appearance.default" type="&#x22;system&#x22; | &#x22;light&#x22; | &#x22;dark&#x22;">
  默认颜色模式。选择 `system` 以匹配用户操作系统设置，或选择 `light` 或 `dark` 强制使用特定模式。默认为 `system`。
</ResponseField>

<ResponseField name="appearance.strict" type="boolean">
  当为 `true` 时，隐藏浅色/深色模式切换，使用户无法切换模式。默认为 `false`。
</ResponseField>

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

***

### `fonts`

**类型：** `object`

文档的自定义字体。默认字体因主题而异。支持 [Google Fonts](https://fonts.google.com) 和自托管字体。

<ResponseField name="fonts.family" type="string" required>
  字体系列名称，如 `"Inter"` 或 `"Open Sans"`。支持 [Google Fonts](https://fonts.google.com) 系列名称——这些会自动加载，无需 `source`。
</ResponseField>

<ResponseField name="fonts.weight" type="number">
  字体粗细，如 `400` 或 `700`。可变字体支持小数粗细，如 `550`。
</ResponseField>

<ResponseField name="fonts.source" type="string (uri)">
  托管字体的 URL 或本地字体文件的路径。Google Fonts 不需要此项。

  * 托管：`https://example.com/fonts/MyFont.woff2`
  * 本地：`/fonts/MyFont.woff2`
</ResponseField>

<ResponseField name="fonts.format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
  字体文件格式。使用 `source` 字段时必需。
</ResponseField>

<ResponseField name="fonts.heading" type="object">
  仅用于标题的字体设置覆盖。

  接受与顶级 `fonts` 对象相同的 `family`、`weight`、`source` 和 `format` 字段。
</ResponseField>

<ResponseField name="fonts.body" type="object">
  仅用于正文的字体设置覆盖。

  接受与顶级 `fonts` 对象相同的 `family`、`weight`、`source` 和 `format` 字段。
</ResponseField>

```json docs.json theme={null}
"fonts": {
  "family": "Inter",
  "heading": {
    "family": "Playfair Display"
  }
}
```

***

### `icons`

**类型：** `object`

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

<ResponseField name="icons.library" type="&#x22;fontawesome&#x22; | &#x22;lucide&#x22; | &#x22;tabler&#x22;" required>
  在整个文档中使用的图标库。默认为 `fontawesome`。

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

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

***

### `background`

**类型：** `object`

背景图片、装饰和颜色设置。

<ResponseField name="background.decoration" type="&#x22;gradient&#x22; | &#x22;grid&#x22; | &#x22;windows&#x22;">
  主题的装饰背景图案。
</ResponseField>

<ResponseField name="background.color" type="object">
  浅色和深色模式的自定义背景颜色。

  <Expandable title="background.color">
    <ResponseField name="light" type="string">
      浅色模式的背景颜色。必须是以 `#` 开头的十六进制代码。
    </ResponseField>

    <ResponseField name="dark" type="string">
      深色模式的背景颜色。必须是以 `#` 开头的十六进制代码。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="background.image" type="string 或 object">
  站点的背景图片。提供单个路径或为浅色和深色模式提供单独的路径。

  <Expandable title="background.image">
    <ResponseField name="light" type="string" required>
      浅色模式背景图片的路径。示例：`/background.png`。
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      深色模式背景图片的路径。示例：`/background-dark.png`。
    </ResponseField>
  </Expandable>
</ResponseField>

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

***

### `styling`

**类型：** `object`

精细的视觉样式控制。

<ResponseField name="styling.eyebrows" type="&#x22;section&#x22; | &#x22;breadcrumbs&#x22;">
  页面 eyebrow 的样式（页面顶部显示的标签）。选择 `section` 显示章节名称，或选择 `breadcrumbs` 显示完整导航路径。默认为 `section`。
</ResponseField>

<ResponseField name="styling.latex" type="boolean">
  控制是否加载 LaTeX 样式表。默认情况下，Mintlify 会自动检测内容中的 LaTeX 使用并加载必要的样式表。

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

<ResponseField name="styling.codeblocks" type="&#x22;system&#x22; | &#x22;dark&#x22; | string | object">
  代码块主题。默认为 `"system"`。

  * `"system"`：匹配当前站点模式（浅色或深色）
  * `"dark"`：始终使用深色模式
  * [Shiki 主题](https://shiki.style/themes)名称字符串：将该主题应用于所有代码块
  * 带有 `light` 和 `dark` 键的对象：为每种模式应用单独的 Shiki 主题

  <Expandable title="styling.codeblocks object">
    <ResponseField name="theme" type="string">
      用于两种模式的单个 Shiki 主题。

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

    <ResponseField name="theme" type="object">
      为浅色和深色模式分别设置 Shiki 主题。

      <Expandable title="theme">
        <ResponseField name="light" type="string" required>
          浅色模式的 Shiki 主题名称。
        </ResponseField>

        <ResponseField name="dark" type="string" required>
          深色模式的 Shiki 主题名称。
        </ResponseField>
      </Expandable>

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

    <ResponseField name="languages" type="object">
      代码块的自定义语言配置。

      <Expandable title="languages">
        <ResponseField name="custom" type="string 数组">
          描述自定义 Shiki 语言的 JSON 文件路径。用于为 Shiki 默认集中没有的语言添加语法高亮。每个文件必须遵循 [TextMate 语法格式](https://macromates.com/manual/en/language_grammars)。

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

***

### `thumbnails`

**类型：** `object`

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

<ResponseField name="thumbnails.appearance" type="&#x22;light&#x22; | &#x22;dark&#x22;">
  缩略图的视觉主题。如果未设置，缩略图使用 `colors` 定义的站点配色方案。
</ResponseField>

<ResponseField name="thumbnails.background" type="string">
  缩略图的背景图片。可以是相对路径或绝对 URL。
</ResponseField>

<ResponseField name="thumbnails.fonts" type="object">
  缩略图的字体配置。仅支持 Google Fonts 系列名称。

  <Expandable title="thumbnails.fonts">
    <ResponseField name="family" type="string" required>
      字体系列名称，如 `"Open Sans"` 或 `"Playfair Display"`。支持 [Google Fonts](https://fonts.google.com) 系列名称。
    </ResponseField>
  </Expandable>
</ResponseField>

## 示例

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