# Global settings (/organize/settings)
Related: [Appearance and branding](/organize/settings-appearance.md), [Site structure](/organize/settings-structure.md), [API settings](/organize/settings-api.md), [Integrations](/organize/settings-integrations.md), [SEO and search](/organize/settings-seo.md), [docs.json schema reference](/organize/settings-reference.md)
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 [#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 [#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 title="docs.json"
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Your project name",
"colors": {
"primary": "#ff0000"
},
"navigation": {
"groups": [
{
"group": "Home",
"pages": ["index"]
}
]
}
}
```
## Settings [#settings]
Customize the visual appearance of your site including theme, colors, logo, favicon, fonts, and background.
Design the information architecture and UX of your site including the navbar, footer, banner, navigation, and redirects.
Control the display and behavior of API documentation including OpenAPI and AsyncAPI specs, API playground, and code examples.
Connect your site to third-party services for analytics, chat, and more.
Control how search engines index your site including meta tags, search, and page timestamps.
Complete reference for all `docs.json` properties.
## Split configuration with `$ref` [#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 title="docs.json"
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Acme Docs",
"colors": {
"primary": "#1a73e8"
},
"navigation": {
"$ref": "./config/navigation.json"
}
}
```
```json title="config/navigation.json"
{
"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.
### Merge sibling keys [#merge-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 title="docs.json"
{
"appearance": {
"$ref": "./config/appearance.json",
"strict": true
}
}
```
## Upgrade from `mint.json` [#upgrade-from-mintjson]
If your project uses the deprecated `mint.json` file, use the [CLI](/cli) to upgrade to `docs.json`.
If you haven't installed the [CLI](/cli/install), install it now:
npm
yarn
pnpm
```bash
npm i -g mint
```
```bash
yarn global add mint
```
```bash
pnpm add -g mint
```
If you already have the CLI installed, make sure it is up to date:
```bash
mint update
```
In your docs repository, run:
```bash
mint dev
```
This command creates a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.
After verifying your `docs.json` is configured correctly, you can safely delete your old `mint.json` file.