feat(docs): add layout.api-reference-layout to docs.yml

docs-yml.schema.json

@@ -5991,6 +5991,13 @@
         "classic"
       ]
     },
+    "docs.ApiReferenceLayout": {
+      "type": "string",
+      "enum": [
+        "indented",
+        "cards"
+      ]
+    },
     "docs.LayoutConfig": {
       "type": "object",
       "properties": {
@@ -6148,6 +6155,17 @@
           ],
           "description": "Sets which layout to use for changelog pages.\n\n@default: `timeline`\n\n- `timeline` renders the searchable timeline-of-cards layout.\n- `classic` renders the legacy stacked-entries layout with a per-page table of contents."
         },
+        "api-reference-layout": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.ApiReferenceLayout"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Sets how nested object fields are rendered in the API reference.\n\n@default: `indented`\n\n- `indented` renders each nested level as an indented branch with a connector line and a color-coded path breadcrumb.\n- `cards` renders each nested level as a bordered card."
+        },
         "show-nav-availability-badges": {
           "oneOf": [
             {

fern-yml.schema.json

@@ -2897,6 +2897,13 @@
                 "classic"
               ]
             },
+            "api-reference-layout": {
+              "type": "string",
+              "enum": [
+                "indented",
+                "cards"
+              ]
+            },
             "show-nav-availability-badges": {
               "type": "boolean"
             }

fern/apis/docs-yml/definition/docs.yml

@@ -1005,6 +1005,17 @@ types:
           - `timeline` renders the searchable timeline-of-cards layout.
           - `classic` renders the legacy stacked-entries layout with a per-page table of contents.
 
+      api-reference-layout:
+        type: optional<ApiReferenceLayout>
+        availability: in-development
+        docs: |
+          Sets how nested object fields are rendered in the API reference.
+
+          @default: `indented`
+
+          - `indented` renders each nested level as an indented branch with a connector line and a color-coded path breadcrumb.
+          - `cards` renders each nested level as a bordered card.
+
       show-nav-availability-badges:
         type: optional<boolean>
         availability: in-development
@@ -1249,6 +1260,11 @@ types:
       - timeline
       - classic
 
+  ApiReferenceLayout:
+    enum:
+      - indented
+      - cards
+
   AudienceId:
     type: string
     docs: ID of audience which is used to filter the API spec.

packages/cli/cli/changes/unreleased/api-reference-layout.yml

@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=../../../../../fern-changes-yml.schema.json
+
+- summary: |
+    Add a `layout.api-reference-layout` option to docs.yml. Set it to `cards` to render
+    nested API reference fields as bordered cards, or `indented` (the default) to render
+    each nested level as an indented branch with a connector line and a path breadcrumb.
+  type: feat

packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts

@@ -676,6 +676,11 @@ function convertLayoutConfig(
         // fern-platform companion PR. Part of the `as unknown as` cast below
         // until the published FDR SDK adds `changelogLayout`.
         changelogLayout: layout.changelogLayout,
+        // Passed through as-is (no default): omitted renders the indented
+        // connector-line tree, "cards" renders the legacy nested cards. Resolved
+        // by the fern-platform companion PR. Part of the `as unknown as` cast
+        // below until the published FDR SDK adds `apiReferenceLayout`.
+        apiReferenceLayout: layout.apiReferenceLayout,
         // Opt-in (default off, resolved by the fern-platform companion PR):
         // when true the sidebar renders inline availability badges. Part of the
         // `as unknown as` cast below until the published FDR SDK adds the field.

packages/cli/configuration/src/docs-yml/DocsYmlSchemas.ts

@@ -94,6 +94,8 @@ export const HeaderPosition = z.enum(["fixed", "static"]);
 
 export const ChangelogLayout = z.enum(["timeline", "classic"]);
 
+export const ApiReferenceLayout = z.enum(["indented", "cards"]);
+
 export const ProductSwitcherThemeConfig = z.enum(["default", "toggle", "tabs"]);
 
 export const LanguageSwitcherThemeConfig = z.enum(["default", "minimal"]);
@@ -308,6 +310,7 @@ export const LayoutConfig = z.object({
     "hide-feedback": z.boolean().optional(),
     "mobile-toc": z.boolean().optional(),
     "changelog-layout": ChangelogLayout.optional(),
+    "api-reference-layout": ApiReferenceLayout.optional(),
     "show-nav-availability-badges": z.boolean().optional()
 });
 

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiReferenceLayout.ts

@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export const ApiReferenceLayout = {
+    Indented: "indented",
+    Cards: "cards",
+} as const;
+export type ApiReferenceLayout = (typeof ApiReferenceLayout)[keyof typeof ApiReferenceLayout];

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LayoutConfig.ts

@@ -105,6 +105,15 @@ export interface LayoutConfig {
      * - `classic` renders the legacy stacked-entries layout with a per-page table of contents.
      */
     changelogLayout?: FernDocsConfig.ChangelogLayout;
+    /**
+     * Sets how nested object fields are rendered in the API reference.
+     *
+     * @default: `indented`
+     *
+     * - `indented` renders each nested level as an indented branch with a connector line and a color-coded path breadcrumb.
+     * - `cards` renders each nested level as a bordered card.
+     */
+    apiReferenceLayout?: FernDocsConfig.ApiReferenceLayout;
     /**
      * If `show-nav-availability-badges` is set to true, availability badges (Beta, Deprecated, etc.)
      * are rendered inline next to navigation items in the sidebar. Defaults to false. The page-header

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts

@@ -10,6 +10,7 @@ export * from "./AnalyticsConfig.js";
 export * from "./AnnouncementConfig.js";
 export * from "./ApiReferenceConfiguration.js";
 export * from "./ApiReferenceEndpointConfiguration.js";
+export * from "./ApiReferenceLayout.js";
 export * from "./ApiReferenceLayoutItem.js";
 export * from "./ApiReferenceOperationConfiguration.js";
 export * from "./ApiReferencePackageConfiguration.js";

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiReferenceLayout.ts

@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as FernDocsConfig from "../../../../api/index.js";
+import * as core from "../../../../core/index.js";
+import type * as serializers from "../../../index.js";
+
+export const ApiReferenceLayout: core.serialization.Schema<
+    serializers.ApiReferenceLayout.Raw,
+    FernDocsConfig.ApiReferenceLayout
+> = core.serialization.enum_(["indented", "cards"]);
+
+export declare namespace ApiReferenceLayout {
+    export type Raw = "indented" | "cards";
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/LayoutConfig.ts

@@ -3,6 +3,7 @@
 import type * as FernDocsConfig from "../../../../api/index.js";
 import * as core from "../../../../core/index.js";
 import type * as serializers from "../../../index.js";
+import { ApiReferenceLayout } from "./ApiReferenceLayout.js";
 import { ChangelogLayout } from "./ChangelogLayout.js";
 import { ContentAlignment } from "./ContentAlignment.js";
 import { HeaderPosition } from "./HeaderPosition.js";
@@ -26,6 +27,7 @@ export const LayoutConfig: core.serialization.ObjectSchema<serializers.LayoutCon
         hideFeedback: core.serialization.property("hide-feedback", core.serialization.boolean().optional()),
         mobileToc: core.serialization.property("mobile-toc", core.serialization.boolean().optional()),
         changelogLayout: core.serialization.property("changelog-layout", ChangelogLayout.optional()),
+        apiReferenceLayout: core.serialization.property("api-reference-layout", ApiReferenceLayout.optional()),
         showNavAvailabilityBadges: core.serialization.property(
             "show-nav-availability-badges",
             core.serialization.boolean().optional(),
@@ -48,6 +50,7 @@ export declare namespace LayoutConfig {
         "hide-feedback"?: boolean | null;
         "mobile-toc"?: boolean | null;
         "changelog-layout"?: ChangelogLayout.Raw | null;
+        "api-reference-layout"?: ApiReferenceLayout.Raw | null;
         "show-nav-availability-badges"?: boolean | null;
     }
 }

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts

@@ -10,6 +10,7 @@ export * from "./AnalyticsConfig.js";
 export * from "./AnnouncementConfig.js";
 export * from "./ApiReferenceConfiguration.js";
 export * from "./ApiReferenceEndpointConfiguration.js";
+export * from "./ApiReferenceLayout.js";
 export * from "./ApiReferenceLayoutItem.js";
 export * from "./ApiReferenceOperationConfiguration.js";
 export * from "./ApiReferencePackageConfiguration.js";

packages/cli/workspace/loader/src/docs-yml.schema.json

@@ -5991,6 +5991,13 @@
         "classic"
       ]
     },
+    "docs.ApiReferenceLayout": {
+      "type": "string",
+      "enum": [
+        "indented",
+        "cards"
+      ]
+    },
     "docs.LayoutConfig": {
       "type": "object",
       "properties": {
@@ -6148,6 +6155,17 @@
           ],
           "description": "Sets which layout to use for changelog pages.\n\n@default: `timeline`\n\n- `timeline` renders the searchable timeline-of-cards layout.\n- `classic` renders the legacy stacked-entries layout with a per-page table of contents."
         },
+        "api-reference-layout": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.ApiReferenceLayout"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Sets how nested object fields are rendered in the API reference.\n\n@default: `indented`\n\n- `indented` renders each nested level as an indented branch with a connector line and a color-coded path breadcrumb.\n- `cards` renders each nested level as a bordered card."
+        },
         "show-nav-availability-badges": {
           "oneOf": [
             {