> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Global settings

> Configure your Mintlify documentation site with docs.json, the required configuration file that controls navigation, appearance, integrations, and more.

The `docs.json` file is the central configuration file for your Mintlify documentation site. It controls the global settings for your site including visual branding, navigation structure, integrations, API settings, and more. Think of it as the blueprint for your site.

## Required fields

You must define four fields to build a working site.

| Field            | Description                                         |
| ---------------- | --------------------------------------------------- |
| `name`           | Your project or organization name                   |
| `theme`          | The layout [theme](/customize/themes) for your site |
| `colors.primary` | Primary brand color as a hex code                   |
| `navigation`     | Your content structure                              |

All other fields are optional. Add them as you customize and refine your site.

## Minimal configuration

For the best editing experience, include the `$schema` reference at the top of your `docs.json`. This enables autocomplete, validation, and inline documentation in most editors.

```json docs.json theme={null}
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your project name",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    "groups": [
      {
        "group": "Home",
        "pages": ["index"]
      }
    ]
  }
}
```

## Settings

<CardGroup cols={2}>
  <Card title="Appearance and branding" icon="palette" href="/organize/settings-appearance">
    Customize the visual appearance of your site including theme, colors, logo, favicon, fonts, and background.
  </Card>

  <Card title="Site structure" icon="layout-panel-left" href="/organize/settings-structure">
    Design the information architecture and UX of your site including the navbar, footer, banner, navigation, and redirects.
  </Card>

  <Card title="API settings" icon="square-terminal" href="/organize/settings-api">
    Control the display and behavior of API documentation including OpenAPI and AsyncAPI specs, API playground, and code examples.
  </Card>

  <Card title="Integrations" icon="plug" href="/organize/settings-integrations">
    Connect your site to third-party services for analytics, chat, and more.
  </Card>

  <Card title="SEO & search" icon="search" href="/organize/settings-seo">
    Control how search engines index your site including meta tags, search, and page timestamps.
  </Card>

  <Card title="Schema reference" icon="code" href="/organize/settings-reference">
    Complete reference for all `docs.json` properties.
  </Card>
</CardGroup>

## Split configuration with `$ref`

As your configuration grows, you can break `docs.json` into smaller files using `$ref` references. Each reference points to a separate JSON file that gets resolved at build time.

Add a `$ref` property with a relative file path anywhere in your `docs.json`. Mintlify replaces the `$ref` object with the contents of the referenced file.

```json docs.json theme={null}
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}
```

```json config/navigation.json theme={null}
{
  "groups": [
    {
      "group": "Get started",
      "pages": ["index", "quickstart"]
    },
    {
      "group": "Guides",
      "pages": ["guides/first-steps", "guides/advanced"]
    }
  ]
}
```

* Referenced files can contain their own `$ref` references. Nested paths resolve relative to the file that contains them, not relative to `docs.json`.
* References must point to valid JSON files.
* Paths must be relative and stay within the project root. Path traversal (for example, `../../outside`) is not allowed.
* Circular references cause a build error.

### Merging sibling keys

If a `$ref` resolves to an object, Mintlify merges any sibling keys in the same block on top of the referenced content, allowing those keys to take precedence over matching keys in the reference. If a `$ref` resolves to a non-object value such as an array, Mintlify ignores any sibling keys.

```json docs.json theme={null}
{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}
```

## Upgrading from `mint.json`

If your project uses the deprecated `mint.json` file, use the [CLI](/cli) to upgrade to `docs.json`.

<Steps>
  <Step title="Install or update the CLI">
    If you haven't installed the [CLI](/cli/install), install it now:

    <CodeGroup>
      ```bash npm theme={null}
      npm i -g mint
      ```

      ```bash yarn theme={null}
      yarn global add mint
      ```

      ```bash pnpm theme={null}
      pnpm add -g mint
      ```
    </CodeGroup>

    If you already have the CLI installed, make sure it is up to date:

    ```bash theme={null}
    mint update
    ```
  </Step>

  <Step title="Create your docs.json file">
    In your docs repository, run:

    ```bash theme={null}
    mint dev
    ```

    This command creates a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
  </Step>

  <Step title="Delete your mint.json file">
    After verifying your `docs.json` is configured correctly, you can safely delete your old `mint.json` file.
  </Step>
</Steps>


## Related topics

- [Navigation](/docs/organize/navigation.md)
- [SEO](/docs/optimize/seo.md)
- [Integrations](/docs/organize/settings-integrations.md)