跳转到主要内容
docs.json 文件可将一组 Markdown 文件转换为可浏览、可自定义的文档站点。这个必填的配置文件控制样式、导航、integrations 等内容。可以把它看作你的文档蓝图。 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。查看主题以了解更多信息。
​
name
string
required
你的项目、组织或产品名称。
​
colors
object
required
文档中使用的配色。不同主题对颜色的应用方式有所不同。如果你只提供主色，它将用于所有颜色元素。
​
description
string
你的网站说明，用于 SEO（搜索引擎优化）和 AI 索引编入。
为浅色和深色模式设置 logo。
​
favicon
string or object
指向 favicon 文件的路径（包含文件扩展名）。会自动调整为合适的 favicon 尺寸。可以是单个文件，或分别为浅色和深色模式提供文件。示例：/favicon.png
​
thumbnails
object
用于社交媒体和页面预览的缩略图自定义。
​
styling
object
视觉样式配置。
​
icons
object
图标库设置。
​
fonts
object
为文档设置自定义字体。默认字体随主题不同而变化。
​
appearance
object
明/暗模式切换设置。
​
background
object
背景颜色与装饰设置。

​
结构

​
navbar
object
导航栏中的外部链接项目。
​
导航
object
required
内容的导航结构。
​
interaction
object
导航元素的用户交互设置。
​
metadata
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
错误处理设置。

​
示例

  • 基础示例
  • 交互式 API 示例
  • 多语言示例
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": "文档",
        "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"
    },
    "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 文件。