From f25feb2b49bc8f40df55c00696738421ad6ad310 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 11 Sep 2026 17:05:36 +0000
Subject: [PATCH] docs: add layout.api-reference-expand-properties

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../docs/pages/api-references/customize-api-ref.mdx        | 7 +++++++
 fern/products/docs/pages/changelog/2026-09-11.mdx          | 7 +++++++
 .../products/docs/pages/navigation/site-level-settings.mdx | 5 +++++
 3 files changed, 19 insertions(+)
 create mode 100644 fern/products/docs/pages/changelog/2026-09-11.mdx

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 a3a44e53c3..c31c6677ca 100644
--- a/fern/products/docs/pages/api-references/customize-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -111,6 +111,13 @@ layout:
   api-reference-layout: cards
 ```
 
+Nested fields are collapsed behind a **Show N properties** button by default. To expand the first level on page load, set [`layout.api-reference-expand-properties`](/learn/docs/configuration/site-level-settings#layoutapi-reference-expand-properties) to `true`. Deeper levels stay collapsed.
+
+```yaml title="docs.yml"
+layout:
+  api-reference-expand-properties: true
+```
+
 ### Renaming sections
 
 By default, section display names come from tag names in your OpenAPI spec.
diff --git a/fern/products/docs/pages/changelog/2026-09-11.mdx b/fern/products/docs/pages/changelog/2026-09-11.mdx
new file mode 100644
index 0000000000..6301688d99
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-09-11.mdx
@@ -0,0 +1,7 @@
+## Expand nested properties by default
+
+<ChangelogTags>api-reference, docs.yml</ChangelogTags>
+
+You can now render the first level of nested object and union fields in your API Reference expanded on page load, so readers see request and response properties without selecting **Show N properties**. Deeper levels stay collapsed. Set `layout.api-reference-expand-properties: true` in `docs.yml` to enable it.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/site-level-settings#layoutapi-reference-expand-properties">Read the docs</Button>
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index b9bb4c57c6..0d4a3335f8 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -591,6 +591,7 @@ layout:
   hide-feedback: true
   changelog-layout: timeline
   api-reference-layout: indented
+  api-reference-expand-properties: true
   show-nav-availability-badges: true
 ```
 
@@ -672,6 +673,10 @@ layout:
   Schemas with several levels of nesting benefit most from `indented`, where card borders otherwise stack into hard-to-follow frames.
 </ParamField>
 
+<ParamField path="layout.api-reference-expand-properties" type="boolean" required={false} default="false" toc={true}>
+  If set to true, the first level of nested object and union fields in the [API Reference](/learn/docs/api-references/generate-api-ref) renders expanded on page load instead of behind a **Show N properties** button. Deeper levels stay collapsed. Applies site-wide.
+</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>