From 8106d6611a5cdfdae0858cc50aa08bfcd717e953 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 21:47:51 +0000 Subject: [PATCH 1/3] Add documentation for composable docs.json with ref support Generated-By: mintlify-agent --- organize/settings.mdx | 74 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/organize/settings.mdx b/organize/settings.mdx index 6ef944368..4cc430e3f 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -63,6 +63,80 @@ For the best editing experience, include the `$schema` reference at the top of y +## Composable configuration with `$ref` + +As your documentation grows, your `docs.json` file can become large and difficult to manage. You can split your configuration into multiple JSON files using `$ref` references, similar to how OpenAPI specs support `$ref`. + +Any value in your `docs.json` can be replaced with a `$ref` object that points to a separate JSON file. During build and local preview, Mintlify resolves all references and merges them into a single configuration. + +### Basic usage + +Replace any value with `{ "$ref": "./path/to/file.json" }` to load it from a separate file: + +```json docs.json +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Your project name", + "colors": { + "primary": "#ff0000" + }, + "navigation": [ + { "$ref": "./nav/getting-started.json" }, + { "$ref": "./nav/api-reference.json" } + ] +} +``` + +```json nav/getting-started.json +{ + "group": "Getting started", + "pages": ["quickstart", "installation", "configuration"] +} +``` + +```json nav/api-reference.json +{ + "group": "API reference", + "pages": ["api/overview", "api/authentication", "api/endpoints"] +} +``` + +### Nested references + +Referenced files can contain their own `$ref` entries. Mintlify resolves them recursively: + +```json docs.json +{ + "navigation": [ + { "$ref": "./nav/guides.json" } + ] +} +``` + +```json nav/guides.json +{ + "group": "Guides", + "pages": [ + "guides/overview", + { "$ref": "./advanced-pages.json" } + ] +} +``` + +```json nav/advanced-pages.json +["guides/webhooks", "guides/rate-limits"] +``` + +### Rules and limitations + +- **File paths are relative** to the file that contains the `$ref`. +- **Only local JSON files** are supported. Remote URLs are not allowed. +- **Circular references** are detected and rejected with an error. +- **Files must be valid JSON.** Syntax errors in referenced files surface clear error messages. +- **Referenced files must be inside your project directory.** Paths that traverse outside the project root are rejected. +- During local preview, changes to referenced files trigger an automatic refresh. + ## Upgrading from `mint.json` If your project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`. From c2cd44d9ecf007bed5f1f8a6e06e40332675c250 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 23:44:21 +0000 Subject: [PATCH 2/3] Add sibling key and diamond dependency rules to composable config docs Generated-By: mintlify-agent --- organize/settings.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/organize/settings.mdx b/organize/settings.mdx index 4cc430e3f..b95ca08fb 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -135,6 +135,8 @@ Referenced files can contain their own `$ref` entries. Mintlify resolves them re - **Circular references** are detected and rejected with an error. - **Files must be valid JSON.** Syntax errors in referenced files surface clear error messages. - **Referenced files must be inside your project directory.** Paths that traverse outside the project root are rejected. +- **Sibling keys are ignored.** When an object contains a `$ref`, all other keys in that object are discarded. The `$ref` value completely replaces the object. +- **Diamond dependencies are allowed.** The same file can be referenced from multiple places without error. - During local preview, changes to referenced files trigger an automatic refresh. ## Upgrading from `mint.json` From 90eb454ccb7f9ddf6f9b687acfdfb1102aadd8e7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 19 Mar 2026 23:07:17 +0000 Subject: [PATCH 3/3] Update docs: sibling keys merge with objects, add override example Generated-By: mintlify-agent --- organize/settings.mdx | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/organize/settings.mdx b/organize/settings.mdx index b95ca08fb..0878cd83f 100644 --- a/organize/settings.mdx +++ b/organize/settings.mdx @@ -128,6 +128,40 @@ Referenced files can contain their own `$ref` entries. Mintlify resolves them re ["guides/webhooks", "guides/rate-limits"] ``` +### Overriding with sibling keys + +When a `$ref` resolves to an object, you can place additional keys alongside it to extend or override the referenced values: + +```json docs.json +{ + "navigation": [ + { + "$ref": "./nav/auth.json", + "icon": "lock" + } + ] +} +``` + +```json nav/auth.json +{ + "group": "Authentication", + "pages": ["api/login", "api/logout"] +} +``` + +This resolves to a single navigation group with the `icon` key merged in: + +```json +{ + "group": "Authentication", + "pages": ["api/login", "api/logout"], + "icon": "lock" +} +``` + +If both the referenced file and a sibling key define the same property, the sibling key takes precedence. + ### Rules and limitations - **File paths are relative** to the file that contains the `$ref`. @@ -135,7 +169,7 @@ Referenced files can contain their own `$ref` entries. Mintlify resolves them re - **Circular references** are detected and rejected with an error. - **Files must be valid JSON.** Syntax errors in referenced files surface clear error messages. - **Referenced files must be inside your project directory.** Paths that traverse outside the project root are rejected. -- **Sibling keys are ignored.** When an object contains a `$ref`, all other keys in that object are discarded. The `$ref` value completely replaces the object. +- **Sibling keys are merged** when the `$ref` resolves to an object. Any keys alongside the `$ref` are added to the resolved object, and sibling keys override matching keys from the referenced file. When the `$ref` resolves to a non-object value (such as an array), sibling keys are ignored. - **Diamond dependencies are allowed.** The same file can be referenced from multiple places without error. - During local preview, changes to referenced files trigger an automatic refresh.