跳转到主要内容
docs.json 文件可将一组 Markdown 文件构建成可导航、可自定义的文档站点。这个必需的配置文件控制样式、navigation、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。更多信息请参阅 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 文档与交互式操作台的相关设置。
​
seo
object
SEO（搜索引擎优化）索引配置。
​
search
object
搜索展示设置。

​
集成

​
集成
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"
    },
    "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 文件。