跳转到主要内容
docs.json 文件可将一组 Markdown 文件构建为可导航、可定制的文档站点。这个必需的配置文件控制样式、导航、集成等内容。可以把它看作你的文档蓝图。 docs.json 中的设置会全局应用于所有页面。

​
配置你的 docs.json

入门时，你只需指定 theme、name、colors.primary 和 navigation。其他字段都是可选的，可随着文档需求增长再逐步添加。 为获得最佳编辑体验，请在 docs.json 文件顶部加入模式（schema）引用。这将在大多数代码编辑器中启用自动补全、验证和实用的悬浮提示： 
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "您的文档",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // 您的导航结构
  }
  // 其余配置
}

​
参考

本节提供 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
导航栏条目。
​
导航
object
required
你的内容导航结构。
​
interaction
object
导航元素的用户交互设置。
​
footer
object
页脚内容与社交媒体链接。
​
banner
object
显示在页面顶部的全站横幅。
​
redirects
array of object
为已移动、重命名或删除的页面配置重定向。
​
contextual
object
用于 AI 优化内容与集成的上下文菜单。

​
API 配置

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

​
集成

​
集成
object
第三方集成。

​
错误

​
errors
object
错误处理设置。

​
示例

  • 基础示例
  • 交互式API示例
  • 多语言示例
文档配置文件
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "maple",
  "name": "Example Co.",
  "description": "Example Co. 是一家提供示例内容和占位文本的公司。",
  "colors": {
    "primary": "#3B82F6",
    "light": "#F8FAFC",
    "dark": "#0F172A"
  },
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "文档",
        "icon": "book",
        "description": "如何使用 Example Co. 的产品",
        "groups": [
          {
            "group": "入门",
            "pages": [
              "index",
              "quickstart"
            ]
          },
          {
            "group": "自定义",
            "pages": [
              "settings",
              "users",
              "features"
            ]
          },
          {
            "group": "账单",
            "pages": [
              "billing/overview",
              "billing/payments",
              "billing/subscriptions"
            ]
          }
        ]
      },
      {
        "dropdown": "变更日志",
        "icon": "history",
        "description": "更新与变更",
        "pages": [
          "changelog"
        ]
      }
    ]
  },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg",
    "href": "https://example.com"
  },
  "navbar": {
    "links": [
      {
        "label": "社区",
        "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 文件。