From 069a41bad4c27af1152485cf3003d8380e4e5796 Mon Sep 17 00:00:00 2001
From: "rishabh.dhadda" <rishabh.dhadda@postman.com>
Date: Tue, 11 Aug 2026 19:58:05 +0000
Subject: [PATCH] Document layout.api-reference-layout

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../docs/pages/api-references/customize-api-ref.mdx    |  9 +++++++++
 .../docs/pages/navigation/site-level-settings.mdx      | 10 ++++++++++
 2 files changed, 19 insertions(+)

diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx
index 1384e1103..3791ad4bf 100644
--- a/fern/products/docs/pages/api-references/customize-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -102,6 +102,15 @@ Required and optional properties always render as separate groups. You can't mix
 
 ## Customizing the API Reference
 
+### Nested object fields
+
+Nested object fields render as indented branches with a connector line and a breadcrumb showing each field's full path. To render them as bordered cards instead, set [`layout.api-reference-layout`](/learn/docs/configuration/site-level-settings#layoutapi-reference-layout) to `cards`. The setting applies site-wide.
+
+```yaml title="docs.yml"
+layout:
+  api-reference-layout: cards
+```
+
 ### Renaming sections
 
 By default, section display names come from tag names in your OpenAPI spec.
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index f6b760462..ab81d0feb 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -584,6 +584,7 @@ layout:
   hide-nav-links: true
   hide-feedback: true
   changelog-layout: timeline
+  api-reference-layout: indented
   show-nav-availability-badges: true
 ```
 
@@ -656,6 +657,15 @@ layout:
   Individual changelogs can override this setting with the `layout` frontmatter property in their [overview page](/learn/docs/configuration/changelogs#add-an-overview-page-optional).
 </ParamField>
 
+<ParamField path="layout.api-reference-layout" type="string" required={false} default="indented" toc={true}>
+  Sets how nested object fields are rendered in the [API Reference](/learn/docs/api-references/generate-api-ref). Can be `indented` or `cards`.
+
+  - `indented` (default) — each nested level is an indented branch with a connector line and a breadcrumb showing the field's full path, so the depth and location of a field stay visible while reading. Breadcrumb segments link to the levels above them.
+  - `cards` — each nested level is a bordered card.
+
+  Schemas with several levels of nesting benefit most from `indented`, where card borders otherwise stack into hard-to-follow frames.
+</ParamField>
+
 <ParamField path="layout.show-nav-availability-badges" type="boolean" required={false} default="false" toc={true}>
   If set to true, availability badges (Beta, Deprecated, etc.) are rendered inline next to navigation items in the sidebar (in addition to the badge rendered automatically in the page header).
 </ParamField>