Document composable docs.json with $ref support

organize/settings.mdx

@@ -63,6 +63,116 @@ For the best editing experience, include the `$schema` reference at the top of y
   </Card>
 </CardGroup>
 
+## 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"]
+```
+
+### 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`.
+- **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.
+- **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.
+
 ## Upgrading from `mint.json`
 
 If your project uses the deprecated `mint.json` file, follow these steps to upgrade to `docs.json`.