mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
7b8b855ff6
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
393 lines
11 KiB
Plaintext
393 lines
11 KiB
Plaintext
---
|
||
title: "外观与品牌"
|
||
description: "在 docs.json 中配置主题、颜色、logo、favicon、字体和背景。"
|
||
keywords: ["主题", "颜色", "logo", "favicon", "字体", "背景", "外观", "品牌", "深色模式", "图标", "样式", "docs.json"]
|
||
---
|
||
|
||
|
||
使用这些 `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
|
||
"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
|
||
"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
|
||
"favicon": "/favicon.svg"
|
||
```
|
||
|
||
---
|
||
|
||
### `appearance`
|
||
|
||
**类型：** `object`
|
||
|
||
浅色/深色模式设置。
|
||
|
||
<ResponseField name="appearance.default" type='"system" | "light" | "dark"'>
|
||
默认颜色模式。选择 `system` 以匹配用户操作系统设置，或选择 `light` 或 `dark` 强制使用特定模式。默认为 `system`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="appearance.strict" type="boolean">
|
||
当为 `true` 时，隐藏浅色/深色模式切换，使用户无法切换模式。默认为 `false`。
|
||
</ResponseField>
|
||
|
||
```json docs.json
|
||
"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='"woff" | "woff2"'>
|
||
字体文件格式。使用 `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
|
||
"fonts": {
|
||
"family": "Inter",
|
||
"heading": {
|
||
"family": "Playfair Display"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `icons`
|
||
|
||
**类型：** `object`
|
||
|
||
图标库设置。每个项目只能使用一个图标库。文档中的所有图标名称必须来自所选的图标库。
|
||
|
||
<ResponseField name="icons.library" type='"fontawesome" | "lucide" | "tabler"' required>
|
||
在整个文档中使用的图标库。默认为 `fontawesome`。
|
||
|
||
<Note>
|
||
无论库设置如何，你可以为任何单个图标指定指向外部托管图标的 URL 或项目中图标文件的路径。
|
||
</Note>
|
||
</ResponseField>
|
||
|
||
```json docs.json
|
||
"icons": {
|
||
"library": "lucide"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `background`
|
||
|
||
**类型：** `object`
|
||
|
||
背景图片、装饰和颜色设置。
|
||
|
||
<ResponseField name="background.decoration" type='"gradient" | "grid" | "windows"'>
|
||
主题的装饰背景图案。
|
||
</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
|
||
"background": {
|
||
"decoration": "gradient",
|
||
"color": {
|
||
"light": "#F8FAFC",
|
||
"dark": "#0F172A"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `styling`
|
||
|
||
**类型：** `object`
|
||
|
||
精细的视觉样式控制。
|
||
|
||
<ResponseField name="styling.eyebrows" type='"section" | "breadcrumbs"'>
|
||
页面 eyebrow 的样式（页面顶部显示的标签）。选择 `section` 显示章节名称，或选择 `breadcrumbs` 显示完整导航路径。默认为 `section`。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="styling.latex" type="boolean">
|
||
控制是否加载 LaTeX 样式表。默认情况下，Mintlify 会自动检测内容中的 LaTeX 使用并加载必要的样式表。
|
||
|
||
- 设置为 `true` 可在自动检测失败时强制加载 LaTeX 样式表。
|
||
- 如果你不使用数学表达式，设置为 `false` 可阻止加载 LaTeX 样式表以提高性能。
|
||
</ResponseField>
|
||
|
||
<ResponseField name="styling.codeblocks" type='"system" | "dark" | 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
|
||
"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
|
||
"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
|
||
"styling": {
|
||
"codeblocks": {
|
||
"languages": {
|
||
"custom": ["/languages/my-language.json"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
</ResponseField>
|
||
</Expandable>
|
||
</ResponseField>
|
||
</Expandable>
|
||
</ResponseField>
|
||
|
||
---
|
||
|
||
### `thumbnails`
|
||
|
||
**类型：** `object`
|
||
|
||
社交媒体和页面预览的缩略图自定义。
|
||
|
||
<ResponseField name="thumbnails.appearance" type='"light" | "dark"'>
|
||
缩略图的视觉主题。如果未设置，缩略图使用 `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
|
||
{
|
||
"$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"
|
||
}
|
||
}
|
||
```
|