docs.json 文件可将一组 Markdown 文件构建为一个可导航、可自定义的文档站点。这个必需的配置文件用于控制样式、导航、集成等。可以把它看作你的文档蓝图。 docs.json 中的设置会全局生效，适用于所有页面。

​
配置你的 docs.json

开始使用时，你只需指定 theme、name、colors.primary 和 navigation。其他字段为可选，可随着文档需求的增长逐步添加。 为获得最佳的编辑体验，请在 docs.json 文件顶部添加 schema 引用。这样可在大多数代码编辑器中启用自动补全、校验和实用的悬浮提示： 
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your Docs",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // Your navigation structure
  }
  // The rest of your configuration
}

​
参考

本节提供 docs.json 文件的完整参考。

​
自定义

​
theme
required
站点的布局主题。可选其一：mint、maple、palm、willow、linden、almond、aspen。参见 Themes 了解更多信息。
​
name
string
required
项目、组织或产品的名称。
​
colors
object
required
文档中使用的配色。不同主题的应用方式有所不同。如果只提供主色，将用于所有颜色元素。
​
description
string
站点的描述，用于 SEO 和 AI 索引。
适用于浅色与深色模式的徽标。
​
favicon
string or object
指向 favicon 文件的路径，需包含文件扩展名。将自动调整为合适的 favicon 尺寸。 可以是单个文件，或分别为浅色和深色模式提供文件。示例：/favicon.png
​
thumbnails
object
用于社交媒体与页面预览的缩略图自定义。
​
styling
object
视觉样式配置。
​
icons
object
图标库设置。
​
fonts
object
文档的字体配置。默认字体为 Inter。
​
appearance
object
明/暗模式切换设置。
​
background
object
背景颜色与装饰设置。

​
结构

​
navbar
object
导航栏条目。
​
navigation
object
required
你的内容导航结构。
​
interaction
object
导航元素的用户交互设置。
​
footer
object
页脚内容和社交媒体链接。
​
banner
object
显示在页面顶部的全站横幅。
​
redirects
array of object
针对已移动、重命名或删除页面的重定向。
​
contextual
object
面向 AI 优化内容与集成的上下文菜单。

​
API 配置

​
api
object
API 文档与交互式操作台的设置。
​
seo
object
SEO 索引配置。
​
search
object
搜索显示设置。

​
集成

​
integrations
object
第三方集成。

​
错误

​
errors
object
错误处理设置。

​
示例

docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. 是一家提供示例内容和占位文本的公司。",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book",
        "description": "如何使用 Example Co. 的产品",
        "groups": [
          {
            "group": "开始上手",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "自定义",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "计费",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "Changelog",
        "icon": "history",
        "description": "更新与变更",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "label": "Community",
        "href": "https://example.com/community"
      }
    ],
    "primary": {
      "type": "button",
      "label": "开始使用",
      "href": "https://example.com/start"
    }
  },
  "footer": {
    "socials": {
      "x": "https://x.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "github": "https://github.com/example",
      "slack": "https://example.com/community"
    },
    "links": [
      {
        "header": "资源",
        "items": [
          {
            "label": "客户",
            "href": "https://example.com/customers"
          },
          {
            "label": "企业版",
            "href": "https://example.com/enterprise"
          },
          {
            "label": "申请试用",
            "href": "https://example.com/preview"
          }
        ]
      },
      {
        "header": "公司",
        "items": [
          {
            "label": "招聘",
            "href": "https://example.com/careers"
          },
          {
            "label": "博客",
            "href": "https://example.com/blog"
          },
          {
            "label": "隐私政策",
            "href": "https://example.com/legal/privacy"
          }
        ]
      }
    ]
  },
  "integrations": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "koala": {
      "publicApiKey": "pk_example_key_123"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "contextual": {
    "options": [
      "copy",
      "view",
      "chatgpt",
      "claude"
    ]
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "未找到页面",
      "description": "这 个 _页面_ 到底**怎么了**？"
    }
  }
}

​
从 mint.json 升级

如果你的文档项目仍在使用已弃用的 mint.json 文件，请按以下步骤升级到 docs.json。
1

安装或更新 CLI

如果你尚未安装 CLI，请先安装：
npm i -g mint
如果你已经安装了 CLI，请确保版本为最新：
mint update
2

创建 docs.json 文件

在你的文档代码库中运行：
mint upgrade
该命令会根据现有的 mint.json 生成一个 docs.json 文件。请检查生成的文件，确保所有设置正确。
3

删除 mint.json 文件

在确认 docs.json 配置无误后，你可以安全删除旧的 mint.json 文件。